Merge pull request #1626 from xiemaisi/js/more-examples

Approved by asger-semmle
2026-05-01 11:45:14 +02:00 · 2019-07-24 14:15:04 +01:00
parent b7be2f5045 74397daeb8
commit 2a292c7dee
4 changed files with 668 additions and 51 deletions
--- a/javascript/ql/src/semmle/javascript/ES2015Modules.qll
+++ b/javascript/ql/src/semmle/javascript/ES2015Modules.qll
@@ -4,6 +4,14 @@ import javascript

 /**
 * An ECMAScript 2015 module.
+ *
+ * Example:
+ *
+ * ```
+ * import console from 'console';
+ *
+ * console.log("Hello, world!");
+ * ```
 */
 class ES2015Module extends Module {
  ES2015Module() { isES2015Module(this) }
@@ -32,7 +40,16 @@ class ES2015Module extends Module {
  }
 }

-/** An import declaration. */
+/**
+ * An import declaration.
+ *
+ * Examples:
+ *
+ * ```
+ * import console, { log, error as fatal } from 'console';
+ * import * as console from 'console';
+ * ```
+ */
 class ImportDeclaration extends Stmt, Import, @importdeclaration {
  override ES2015Module getEnclosingModule() { result = getTopLevel() }

@@ -71,19 +88,20 @@ private class LiteralImportPath extends PathExprInModule, ConstantString {
 /**
 * An import specifier in an import declaration.
 *
- * There are four kinds of import specifiers:
+ * Examples:
 *
- *   - default import specifiers, which import the default export of a module
- *     and make it available under a local name, as in `import` <u>`f`</u> `from 'a'`;
- *   - namespace import specifiers, which import all exports of a module and
- *     make them available through a local namespace object, as in
- *     `import` <u>`* as ns`</u> `from 'a'`;
- *   - named import specifiers, which import a named export of a module and
- *     make it available in the importing module under the same name, as in
- *     `import {` <u>`x`</u> `} from 'a'`;
- *   - renaming import specifiers, which import a named export of a module and
- *     make it available in the importing module under a different name, as in
- *     `import {` <u>`x as y`</u> `} from 'a'`.
+ * ```
+ * import
+ *   console,            // default import specifier
+ *   {
+ *     log,              // named import specifier
+ *     error as fatal    // renaming import specifier
+ *   } from 'console';
+ *
+ * import
+ *   * as console        // namespace import specifier
+ *   from 'console';
+ * ```
 */
 class ImportSpecifier extends Expr, @importspecifier {
  /** Gets the imported symbol; undefined for default and namespace import specifiers. */
@@ -110,18 +128,58 @@ class ImportSpecifier extends Expr, @importspecifier {
  VarDecl getLocal() { result = getChildExpr(1) }
 }

-/** A named import specifier. */
+/**
+ * A named import specifier.
+ *
+ * Examples:
+ *
+ * ```
+ * import
+ *   {
+ *     log,              // named import specifier
+ *     error as fatal    // renaming import specifier
+ *   } from 'console';
+ * ```
+ */
 class NamedImportSpecifier extends ImportSpecifier, @namedimportspecifier { }

-/** A default import specifier. */
+/**
+ * A default import specifier.
+ *
+ * Example:
+ *
+ * ```
+ * import
+ *   console             // default import specifier
+ *   from 'console';
+ * ```
+ */
 class ImportDefaultSpecifier extends ImportSpecifier, @importdefaultspecifier {
  override string getImportedName() { result = "default" }
 }

-/** A namespace import specifier. */
+/**
+ * A namespace import specifier.
+ *
+ * Example:
+ *
+ * ```
+ * import
+ *   * as console        // namespace import specifier
+ *   from 'console';
+ * ```
+ */
 class ImportNamespaceSpecifier extends ImportSpecifier, @importnamespacespecifier { }

-/** A bulk import that imports an entire module as a namespace. */
+/**
+ * A bulk import that imports an entire module as a namespace.
+ *
+ * Example:
+ *
+ * ```
+ * import * as console from 'console';
+ * ```
+ */
 class BulkImportDeclaration extends ImportDeclaration {
  BulkImportDeclaration() { getASpecifier() instanceof ImportNamespaceSpecifier }

@@ -129,7 +187,15 @@ class BulkImportDeclaration extends ImportDeclaration {
  VarDecl getLocal() { result = getASpecifier().getLocal() }
 }

-/** A selective import that imports zero or more declarations. */
+/**
+ * A selective import that imports zero or more declarations.
+ *
+ * Example:
+ *
+ * ```
+ * import console, { log } from 'console';
+ * ```
+ */
 class SelectiveImportDeclaration extends ImportDeclaration {
  SelectiveImportDeclaration() { not this instanceof BulkImportDeclaration }

@@ -147,16 +213,20 @@ class SelectiveImportDeclaration extends ImportDeclaration {
 /**
 * An export declaration.
 *
- * There are three kinds of export declarations:
+ * Examples:
 *
- *   - a bulk re-export declaration of the form `export * from 'a'`, which re-exports
- *     all exports of another module;
- *   - a default export declaration of the form `export default var x = 42`, which exports
- *     a local value or declaration as the default export;
- *   - a named export declaration such as `export { x, y as z }`, which exports local
- *     values or declarations under specific names; a named export declaration
- *     may also export symbols itself imported from another module, as in
- *     `export { x } from 'a'`.
+ * ```
+ * export * from 'a';               // bulk re-export declaration
+ *
+ * export default var x = 42;       // default export declaration
+ * export default function f() {};  // default export declaration
+ * export default 42;               // default export declaration
+ *
+ * export { x, y as z };            // named export declaration
+ * export var x = 42;               // named export declaration
+ * export { x } from 'a';           // named re-export declaration
+ * export x from 'a';               // default re-export declaration
+ * ```
 */
 abstract class ExportDeclaration extends Stmt, @exportdeclaration {
  /** Gets the module to which this export declaration belongs. */
@@ -192,6 +262,12 @@ abstract class ExportDeclaration extends Stmt, @exportdeclaration {
 /**
 * A bulk re-export declaration of the form `export * from 'a'`, which re-exports
 * all exports of another module.
+ *
+ * Examples:
+ *
+ * ```
+ * export * from 'a';          // bulk re-export declaration
+ * ```
 */
 class BulkReExportDeclaration extends ReExportDeclaration, @exportalldeclaration {
  /** Gets the name of the module from which this declaration re-exports. */
@@ -229,8 +305,15 @@ private predicate isShadowedFromBulkExport(BulkReExportDeclaration reExport, str
 }

 /**
- * A default export declaration such as `export default function f{}`
- * or `export default { x: 42 }`.
+ * A default export declaration.
+ *
+ * Examples:
+ *
+ * ```
+ * export default var x = 42;
+ * export default function f() {};
+ * export default 42;
+ * ```
 */
 class ExportDefaultDeclaration extends ExportDeclaration, @exportdefaultdeclaration {
  /** Gets the operand statement or expression that is exported by this declaration. */
@@ -253,7 +336,16 @@ class ExportDefaultDeclaration extends ExportDeclaration, @exportdefaultdeclarat
  }
 }

-/** A named export declaration such as `export { x, y }` or `export var x = 42`. */
+/** A named export declaration.
+ *  *
+ * Examples:
+ *
+ * ```
+ * export { x, y as z };
+ * export var x = 42;
+ * export { x } from 'a';
+ * ```
+ * */
 class ExportNamedDeclaration extends ExportDeclaration, @exportnameddeclaration {
  /** Gets the operand statement or expression that is exported by this declaration. */
  ExprOrStmt getOperand() { result = getChild(-1) }
@@ -322,7 +414,30 @@ class ExportNamedDeclaration extends ExportDeclaration, @exportnameddeclaration
  }
 }

-/** An export specifier in a named export declaration. */
+/**
+ * An export specifier in an export declaration.
+ *
+ * Examples:
+ *
+ * ```
+ * export
+ *   *              // namespace export specifier
+ *   from 'a';
+ *
+ * export
+ *   default        // default export specifier
+ *   var x = 42;
+ *
+ * export {
+ *   x,             // named export specifier
+ *   y as z         // named export specifier
+ * };
+ *
+ * export
+ *   x              // default re-export specifier
+ *   from 'a';
+ * ```
+ */
 class ExportSpecifier extends Expr, @exportspecifier {
  /** Gets the declaration to which this specifier belongs. */
  ExportDeclaration getExportDeclaration() { result = getParent() }
@@ -380,21 +495,47 @@ class ExportSpecifier extends Expr, @exportspecifier {
 }

 /**
- * A named export specifier, for example `v` in `export { v }`.
+ * A named export specifier.
+ *
+ * Examples:
+ *
+ * ```
+ * export {
+ *   x,       // named export specifier
+ *   y as z   // named export specifier
+ * };
+ * ```
 */
 class NamedExportSpecifier extends ExportSpecifier, @namedexportspecifier { }

 /**
- * A default export specifier, for example `default` in `export default 42`,
- * or `v` in `export v from "mod"`.
+ * A default export specifier.
+ *
+ * Examples:
+ *
+ * ```
+ * export
+ *   default    // default export specifier
+ *   42;
+ * export
+ *   x          // default re-export specifier
+ *   from 'a';
+ * ```
 */
 class ExportDefaultSpecifier extends ExportSpecifier, @exportdefaultspecifier {
  override string getExportedName() { result = "default" }
 }

 /**
- * A default export specifier in a re-export declaration, for example `v` in
- * `export v from "mod"`.
+ * A default export specifier in a re-export declaration.
+ *
+ * Example:
+ *
+ * ```
+ * export
+ *   x          // default re-export specifier
+ *   from 'a';
+ * ```
 */
 class ReExportDefaultSpecifier extends ExportDefaultSpecifier {
  ReExportDefaultSpecifier() { getExportDeclaration() instanceof ReExportDeclaration }
@@ -405,11 +546,29 @@ class ReExportDefaultSpecifier extends ExportDefaultSpecifier {
 }

 /**
- * A namespace export specifier, for example `*` in `export * from "mod"`.
+ * A namespace export specifier.
+ *
+ * Example:
+ *
+ * ```
+ * export
+ *   *          // namespace export specifier
+ *   from 'a';
+ * ```
 */
 class ExportNamespaceSpecifier extends ExportSpecifier, @exportnamespacespecifier { }

-/** An export declaration that re-exports declarations from another module. */
+/**
+ * An export declaration that re-exports declarations from another module.
+ *
+ * Examples:
+ *
+ * ```
+ * export * from 'a';               // bulk re-export declaration
+ * export { x } from 'a';           // named re-export declaration
+ * export x from 'a';               // default re-export declaration
+ * ```
+ */
 abstract class ReExportDeclaration extends ExportDeclaration {
  /** Gets the path of the module from which this declaration re-exports. */
  abstract ConstantString getImportedPath();
@@ -441,7 +600,15 @@ private class LiteralReExportPath extends PathExprInModule, ConstantString {
  override string getValue() { result = this.(ConstantString).getStringValue() }
 }

-/** A named export declaration that re-exports symbols imported from another module. */
+/**
+ * A named export declaration that re-exports symbols imported from another module.
+ *
+ * Example:
+ *
+ * ```
+ * export { x } from 'a';
+ * ```
+ */
 class SelectiveReExportDeclaration extends ReExportDeclaration, ExportNamedDeclaration {
  SelectiveReExportDeclaration() { exists(ExportNamedDeclaration.super.getImportedPath()) }

@@ -451,7 +618,19 @@ class SelectiveReExportDeclaration extends ReExportDeclaration, ExportNamedDecla
  }
 }

-/** An export declaration that exports zero or more declarations from the module it appears in. */
+/**
+ * An export declaration that exports zero or more declarations from the module it appears in.
+ *
+ * Examples:
+ *
+ * ```
+ * export default var x = 42;
+ * export default function f() {};
+ * export default 42;
+ * export { x, y as z };
+ * export var x = 42;
+ * ```
+ */
 class OriginalExportDeclaration extends ExportDeclaration {
  OriginalExportDeclaration() { not this instanceof ReExportDeclaration }

--- a/javascript/ql/src/semmle/javascript/Externs.qll
+++ b/javascript/ql/src/semmle/javascript/Externs.qll
@@ -39,7 +39,31 @@

 import javascript

-/** A declaration in an externs file. */
+/**
+ * A declaration in an externs file.
+ *
+ * Examples:
+ *
+ * <pre>
+ * /**
+ *  * @constructor
+ *  * @return {!Object}
+ *  *&#47;
+ * function Object() {}
+ *
+ * /**
+ *  * @param {!Object} obj
+ *  * @return {!Array<string>}
+ *  *&#47;
+ * Object.keys = function(obj) {};
+ *
+ * /**
+ *  * @param {*} p
+ *  * @return {boolean}
+ *  *&#47;
+ * Object.prototype.hasOwnProperty = function(p) {};
+ * </pre>
+ */
 abstract class ExternalDecl extends ASTNode {
  /** Gets the name of this declaration. */
  abstract string getName();
@@ -66,7 +90,35 @@ class ExternalTypedef extends ExternalDecl, VariableDeclarator {
  override string getQualifiedName() { result = getName() }
 }

-/** A variable or function declaration in an externs file. */
+/**
+ * A variable or function declaration in an externs file.
+ *
+ * Examples:
+ *
+ * <pre>
+ * /**
+ *  * @constructor
+ *  * @return {!Object}
+ *  *&#47;
+ * function Object() {}
+ *
+ * /**
+ *  * @type {number}
+ *  *&#47;
+ * var NaN;
+ *
+ * /**
+ *  * @param {!Object} obj
+ *  * @return {!Array<string>}
+ *  *&#47;
+ * Object.keys = function(obj) {};
+ *
+ * /**
+ *  * @type {number}
+ *  *&#47;
+ * Number.NaN;
+ * </pre>
+ */
 abstract class ExternalVarDecl extends ExternalDecl {
  /**
   * Gets the initializer associated with this declaration, if any.
@@ -86,12 +138,41 @@ abstract class ExternalVarDecl extends ExternalDecl {
  ExternalTypeTag getTypeTag() { result = getATag() }
 }

-/** A global declaration of a function or variable in an externs file. */
+/**
+ * A global declaration of a function or variable in an externs file.
+ *
+ * Examples:
+ *
+ * <pre>
+ * /**
+ *  * @constructor
+ *  * @return {!Object}
+ *  *&#47;
+ * function Object() {}
+ *
+ * /**
+ *  * @type {number}
+ *  *&#47;
+ * var NaN;
+ * </pre>
+ */
 abstract class ExternalGlobalDecl extends ExternalVarDecl {
  override string getQualifiedName() { result = getName() }
 }

-/** A global function declaration in an externs file. */
+/**
+ * A global function declaration in an externs file.
+ *
+ * Examples:
+ *
+ * <pre>
+ * /**
+ *  * @constructor
+ *  * @return {!Object}
+ *  *&#47;
+ * function Object() {}
+ * </pre>
+ */
 class ExternalGlobalFunctionDecl extends ExternalGlobalDecl, FunctionDeclStmt {
  ExternalGlobalFunctionDecl() { inExternsFile() }

@@ -101,7 +182,18 @@ class ExternalGlobalFunctionDecl extends ExternalGlobalDecl, FunctionDeclStmt {
  override ASTNode getInit() { result = this }
 }

-/** A global variable declaration in an externs file. */
+/**
+ * A global variable declaration in an externs file.
+ *
+ * Example:
+ *
+ * <pre>
+ * /**
+ *  * @type {number}
+ *  *&#47;
+ * var NaN;
+ * </pre>
+ */
 class ExternalGlobalVarDecl extends ExternalGlobalDecl, VariableDeclarator {
  ExternalGlobalVarDecl() {
    getBindingPattern() instanceof Identifier and
@@ -116,7 +208,22 @@ class ExternalGlobalVarDecl extends ExternalGlobalDecl, VariableDeclarator {
  override Expr getInit() { result = VariableDeclarator.super.getInit() }
 }

-/** A member variable declaration in an externs file. */
+/**
+ * A member variable declaration in an externs file.
+ *
+ * <pre>
+ * /**
+ *  * @param {!Object} obj
+ *  * @return {!Array<string>}
+ *  *&#47;
+ * Object.keys = function(obj) {};
+ *
+ * /**
+ *  * @type {number}
+ *  *&#47;
+ * Number.NaN;
+ * </pre>
+ */
 class ExternalMemberDecl extends ExternalVarDecl, ExprStmt {
  ExternalMemberDecl() {
    getParent() instanceof Externs and
@@ -159,8 +266,20 @@ class ExternalMemberDecl extends ExternalVarDecl, ExprStmt {
 /**
 * A static member variable declaration in an externs file.
 *
- * This captures declarations of the form `A.f;`, and declarations
- * with initializers of the form `A.f = {};`.
+ * Examples:
+ *
+ * <pre>
+ * /**
+ *  * @param {!Object} obj
+ *  * @return {!Array<string>}
+ *  *&#47;
+ * Object.keys = function(obj) {};
+ *
+ * /**
+ *  * @type {number}
+ *  *&#47;
+ * Number.NaN;
+ * </pre>
 */
 class ExternalStaticMemberDecl extends ExternalMemberDecl {
  ExternalStaticMemberDecl() { getProperty().getBase() instanceof Identifier }
@@ -171,8 +290,20 @@ class ExternalStaticMemberDecl extends ExternalMemberDecl {
 /**
 * An instance member variable declaration in an externs file.
 *
- * This captures declarations of the form `A.prototype.f;`, and declarations
- * with initializers of the form `A.prototype.f = {};`.
+ * Examples:
+ *
+ * <pre>
+ * /**
+ *  * @param {*} p
+ *  * @return {boolean}
+ *  *&#47;
+ * Object.prototype.hasOwnProperty = function(p) {};
+ *
+ * /**
+ *  * @type {number}
+ *  *&#47;
+ * Array.prototype.length;
+ * </pre>
 */
 class ExternalInstanceMemberDecl extends ExternalMemberDecl {
  ExternalInstanceMemberDecl() {
@@ -189,6 +320,17 @@ class ExternalInstanceMemberDecl extends ExternalMemberDecl {

 /**
 * A function or object defined in an externs file.
+ *
+ * Example:
+ *
+ * <pre>
+ * /**
+ *  * @param {*} p
+ *  * @return {boolean}
+ *  *&#47;
+ * Object.prototype.hasOwnProperty =
+ *   function(p) {};  // external function entity
+ * </pre>
 */
 class ExternalEntity extends ASTNode {
  ExternalEntity() { exists(ExternalVarDecl d | d.getInit() = this) }
@@ -199,6 +341,17 @@ class ExternalEntity extends ASTNode {

 /**
 * A function defined in an externs file.
+ *
+ * Example:
+ *
+ * <pre>
+ * /**
+ *  * @param {*} p
+ *  * @return {boolean}
+ *  *&#47;
+ * Object.prototype.hasOwnProperty =
+ *   function(p) {};  // external function
+ * </pre>
 */
 class ExternalFunction extends ExternalEntity, Function {
  /**
@@ -216,12 +369,30 @@ class ExternalFunction extends ExternalEntity, Function {

 /**
 * A `@constructor` tag.
+ *
+ * Example:
+ *
+ * <pre>
+ * /**
+ *  * @constructor  // constructor tag
+ *  *&#47;
+ * function Array() {}
+ * </pre>
 */
 class ConstructorTag extends JSDocTag {
  ConstructorTag() { getTitle() = "constructor" }
 }

-/** A JSDoc tag that refers to a named type. */
+/**
+ * A JSDoc tag that refers to a named type.
+ *
+ * Example:
+ *
+ * <pre>
+ * /** @type {number} *&#47;  // refers to named type `number`
+ * var NaN;
+ * </pre>
+ */
 abstract private class NamedTypeReferent extends JSDocTag {
  /** Gets the name of the type to which this tag refers. */
  string getTarget() {
@@ -257,6 +428,13 @@ private ExternalType sourceDecl(JSDocTypeExpr tp) {

 /**
 * An `@implements` tag.
+ *
+ * Example:
+ *
+ * <pre>
+ * /** @implements {EventTarget} *&#47;
+ * function Node() {}
+ * </pre>
 */
 class ImplementsTag extends NamedTypeReferent {
  ImplementsTag() { getTitle() = "implements" }
@@ -264,6 +442,13 @@ class ImplementsTag extends NamedTypeReferent {

 /**
 * An `@extends` tag.
+ *
+ * Example:
+ *
+ * <pre>
+ * /** @extends {Node} *&#47;
+ * function Document() {}
+ * </pre>
 */
 class ExtendsTag extends NamedTypeReferent {
  ExtendsTag() { getTitle() = "extends" }
@@ -271,6 +456,13 @@ class ExtendsTag extends NamedTypeReferent {

 /**
 * A `@type` tag.
+ *
+ * Example:
+ *
+ * <pre>
+ * /** @type {number} *&#47;
+ * var NaN;
+ * </pre>
 */
 class ExternalTypeTag extends NamedTypeReferent {
  ExternalTypeTag() { getTitle() = "type" }
@@ -278,6 +470,21 @@ class ExternalTypeTag extends NamedTypeReferent {

 /**
 * A constructor or interface function defined in an externs file.
+ *
+ * Examples:
+ *
+ * <pre>
+ * /**
+ *  * @constructor
+ *  * @return {!Object}
+ *  *&#47;
+ * function Object() {}
+ *
+ * /**
+ *  * @interface
+ *  *&#47;
+ * function EventTarget() {}
+ * </pre>
 */
 abstract class ExternalType extends ExternalGlobalFunctionDecl {
  /** Gets a type which this type extends. */
@@ -299,6 +506,16 @@ abstract class ExternalType extends ExternalGlobalFunctionDecl {

 /**
 * A constructor function defined in an externs file.
+ *
+ * Example:
+ *
+ * <pre>
+ * /**
+ *  * @constructor
+ *  * @return {!Object}
+ *  *&#47;
+ * function Object() {}
+ * </pre>
 */
 class ExternalConstructor extends ExternalType {
  ExternalConstructor() { getDocumentation().getATag() instanceof ConstructorTag }
@@ -306,6 +523,15 @@ class ExternalConstructor extends ExternalType {

 /**
 * An interface function defined in an externs file.
+ *
+ * Example:
+ *
+ * <pre>
+ * /**
+ *  * @interface
+ *  *&#47;
+ * function EventTarget() {}
+ * </pre>
 */
 class ExternalInterface extends ExternalType {
  ExternalInterface() { getDocumentation().getATag().getTitle() = "interface" }
@@ -313,6 +539,16 @@ class ExternalInterface extends ExternalType {

 /**
 * Externs definition for the Function object.
+ *
+ * Example:
+ *
+ * <pre>
+ * /**
+ *  * @constructor
+ *  * @param {...*} args
+ *  *&#47;
+ * function Function(args) {}
+ * </pre>
 */
 class FunctionExternal extends ExternalConstructor {
  FunctionExternal() { getName() = "Function" }
@@ -320,6 +556,16 @@ class FunctionExternal extends ExternalConstructor {

 /**
 * Externs definition for the Object object.
+ *
+ * Example:
+ *
+ * <pre>
+ * /**
+ *  * @constructor
+ *  * @return {!Object}
+ *  *&#47;
+ * function Object() {}
+ * </pre>
 */
 class ObjectExternal extends ExternalConstructor {
  ObjectExternal() { getName() = "Object" }
@@ -327,6 +573,17 @@ class ObjectExternal extends ExternalConstructor {

 /**
 * Externs definition for the Array object.
+ *
+ * Example:
+ *
+ * <pre>
+ * /**
+ *  * @constructor
+ *  * @param {...*} args
+ *  * @return {!Array}
+ *  *&#47;
+ * function Array(args) {}
+ * </pre>
 */
 class ArrayExternal extends ExternalConstructor {
  ArrayExternal() { getName() = "Array" }
--- a/javascript/ql/src/semmle/javascript/JSON.qll
+++ b/javascript/ql/src/semmle/javascript/JSON.qll
@@ -6,6 +6,18 @@ import javascript

 /**
 * A JSON-encoded value, which may be a primitive value, an array or an object.
+ *
+ * Examples:
+ *
+ * ```
+ * null
+ * true
+ * false
+ * 42
+ * "a string"
+ * [ 1, 2, 3 ]
+ * { "value": 0 }
+ * ```
 */
 class JSONValue extends @json_value, Locatable {
  override Location getLocation() { hasLocation(this, result) }
@@ -24,6 +36,16 @@ class JSONValue extends @json_value, Locatable {

 /**
 * A JSON-encoded primitive value.
+ *
+ * Examples:
+ *
+ * ```
+ * null
+ * true
+ * false
+ * 42
+ * "a string"
+ * ```
 */
 abstract class JSONPrimitiveValue extends JSONValue {
  /** Gets a string representation of the encoded value. */
@@ -35,26 +57,58 @@ abstract class JSONPrimitiveValue extends JSONValue {

 /**
 * A JSON-encoded null value.
+ *
+ * Example:
+ *
+ * ```
+ * null
+ * ```
 */
 class JSONNull extends @json_null, JSONPrimitiveValue { }

 /**
 * A JSON-encoded Boolean value.
+ *
+ * Examples:
+ *
+ * ```
+ * true
+ * false
+ * ```
 */
 class JSONBoolean extends @json_boolean, JSONPrimitiveValue { }

 /**
 * A JSON-encoded number.
+ *
+ * Examples:
+ *
+ * ```
+ * 42
+ * 1.0
+ * ```
 */
 class JSONNumber extends @json_number, JSONPrimitiveValue { }

 /**
 * A JSON-encoded string value.
+ *
+ * Example:
+ *
+ * ```
+ * "a string"
+ * ```
 */
 class JSONString extends @json_string, JSONPrimitiveValue { }

 /**
 * A JSON-encoded array.
+ *
+ * Example:
+ *
+ * ```
+ * [ 1, 2, 3 ]
+ * ```
 */
 class JSONArray extends @json_array, JSONValue {
  /** Gets the value of the `i`th element of this array. */
@@ -66,6 +120,12 @@ class JSONArray extends @json_array, JSONValue {

 /**
 * A JSON-encoded object.
+ *
+ * Example:
+ *
+ * ```
+ * { "value": 0 }
+ * ```
 */
 class JSONObject extends @json_object, JSONValue {
  /** Gets the value of property `name` of this object. */
--- a/javascript/ql/src/semmle/javascript/YAML.qll
+++ b/javascript/ql/src/semmle/javascript/YAML.qll
@@ -11,6 +11,14 @@ import javascript
 * A node in the AST representation of a YAML file, which may either be
 * a YAML value (such as a scalar or a collection) or an alias node
 * referring to some other YAML value.
+ *
+ * Examples:
+ *
+ * ```
+ * # a mapping
+ * x: 1
+ * << : *DEFAULTS  # an alias node referring to anchor `DEFAULTS`
+ * ```
 */
 class YAMLNode extends @yaml_node, Locatable {
  override Location getLocation() { hasLocation(this, result) }
@@ -79,11 +87,32 @@ class YAMLNode extends @yaml_node, Locatable {

 /**
 * A YAML value; that is, either a scalar or a collection.
+ *
+ * Examples:
+ *
+ * ```
+ * ---
+ * "a string"
+ * ---
+ * - a
+ * - sequence
+ * ```
 */
 abstract class YAMLValue extends YAMLNode { }

 /**
 * A YAML scalar.
+ *
+ * Examples:
+ *
+ * ```
+ * 42
+ * 1.0
+ * 2001-12-15T02:59:43.1Z
+ * true
+ * null
+ * "hello"
+ * ```
 */
 class YAMLScalar extends YAMLValue, @yaml_scalar_node {
  /**
@@ -117,6 +146,13 @@ class YAMLScalar extends YAMLValue, @yaml_scalar_node {

 /**
 * A YAML scalar representing an integer value.
+ *
+ * Examples:
+ *
+ * ```
+ * 42
+ * 0xffff
+ * ```
 */
 class YAMLInteger extends YAMLScalar {
  YAMLInteger() { hasStandardTypeTag("int") }
@@ -129,6 +165,13 @@ class YAMLInteger extends YAMLScalar {

 /**
 * A YAML scalar representing a floating point value.
+ *
+ * Examples:
+ *
+ * ```
+ * 1.0
+ * 6.626e-34
+ * ```
 */
 class YAMLFloat extends YAMLScalar {
  YAMLFloat() { hasStandardTypeTag("float") }
@@ -141,6 +184,12 @@ class YAMLFloat extends YAMLScalar {

 /**
 * A YAML scalar representing a time stamp.
+ *
+ * Example:
+ *
+ * ```
+ * 2001-12-15T02:59:43.1Z
+ * ```
 */
 class YAMLTimestamp extends YAMLScalar {
  YAMLTimestamp() { hasStandardTypeTag("timestamp") }
@@ -153,6 +202,12 @@ class YAMLTimestamp extends YAMLScalar {

 /**
 * A YAML scalar representing a Boolean value.
+ *
+ * Example:
+ *
+ * ```
+ * true
+ * ```
 */
 class YAMLBool extends YAMLScalar {
  YAMLBool() { hasStandardTypeTag("bool") }
@@ -165,6 +220,12 @@ class YAMLBool extends YAMLScalar {

 /**
 * A YAML scalar representing the null value.
+ *
+ * Example:
+ *
+ * ```
+ * null
+ * ```
 */
 class YAMLNull extends YAMLScalar {
  YAMLNull() { hasStandardTypeTag("null") }
@@ -172,6 +233,12 @@ class YAMLNull extends YAMLScalar {

 /**
 * A YAML scalar representing a string value.
+ *
+ * Example:
+ *
+ * ```
+ * "hello"
+ * ```
 */
 class YAMLString extends YAMLScalar {
  YAMLString() { hasStandardTypeTag("str") }
@@ -179,6 +246,13 @@ class YAMLString extends YAMLScalar {

 /**
 * A YAML scalar representing a merge key.
+ *
+ * Example:
+ *
+ * ```
+ * x: 1
+ * << : *DEFAULTS  # merge key
+ * ```
 */
 class YAMLMergeKey extends YAMLScalar {
  YAMLMergeKey() { hasStandardTypeTag("merge") }
@@ -186,6 +260,10 @@ class YAMLMergeKey extends YAMLScalar {

 /**
 * A YAML scalar representing an `!include` directive.
+ *
+ * ```
+ * !include common.yaml
+ * ```
 */
 class YAMLInclude extends YAMLScalar {
  YAMLInclude() { getTag() = "!include" }
@@ -211,11 +289,32 @@ class YAMLInclude extends YAMLScalar {

 /**
 * A YAML collection, that is, either a mapping or a sequence.
+ *
+ * Examples:
+ *
+ * ```
+ * ---
+ * # a mapping
+ * x: 0
+ * y: 1
+ * ---
+ * # a sequence
+ * - red
+ * - green
+ * - -blue
+ * ```
 */
 class YAMLCollection extends YAMLValue, @yaml_collection_node { }

 /**
 * A YAML mapping.
+ *
+ * Example:
+ *
+ * ```
+ * x: 0
+ * y: 1
+ * ```
 */
 class YAMLMapping extends YAMLCollection, @yaml_mapping_node {
  /**
@@ -261,6 +360,14 @@ class YAMLMapping extends YAMLCollection, @yaml_mapping_node {

 /**
 * A YAML sequence.
+ *
+ * Example:
+ *
+ * ```
+ * - red
+ * - green
+ * - blue
+ * ```
 */
 class YAMLSequence extends YAMLCollection, @yaml_sequence_node {
  /**
@@ -276,6 +383,12 @@ class YAMLSequence extends YAMLCollection, @yaml_sequence_node {

 /**
 * A YAML alias node referring to a target anchor.
+ *
+ * Example:
+ *
+ * ```
+ * *DEFAULTS
+ * ```
 */
 class YAMLAliasNode extends YAMLNode, @yaml_alias_node {
  override YAMLValue eval() {
@@ -291,6 +404,14 @@ class YAMLAliasNode extends YAMLNode, @yaml_alias_node {

 /**
 * A YAML document.
+ *
+ * Example:
+ *
+ * ```
+ * ---
+ * x: 0
+ * y: 1
+ * ```
 */
 class YAMLDocument extends YAMLNode {
  YAMLDocument() { not exists(getParentNode()) }