JavaScript: Add syntax examples to Comments.qll, E4X.qll, Functions.qll, HTML.qll and NodeJS.qll.

Author: Max Schaefer

javascript/ql/src/semmle/javascript/Comments.qll

@@ -2,7 +2,18 @@
 
 import javascript
 
-/** A JavaScript source code comment. */
+/**
+ * A JavaScript source-code comment.
+ *
+ * Examples:
+ *
+ * <pre>
+ * // a line comment
+ * /* a block
+  *   comment *&#47
+ * &lt;!-- an HTML line comment
+ * </pre>
+ */
 class Comment extends @comment, Locatable {
   override Location getLocation() { hasLocation(this, result) }
 
@@ -32,26 +43,95 @@ class Comment extends @comment, Locatable {
   }
 }
 
-/** A line comment, that is, either an HTML comment or a `//` comment. */
+/**
+ * A line comment, that is, either an HTML comment or a `//` comment.
+ *
+ * Examples:
+ *
+ * <pre>
+ * // a line comment
+ * &lt;!-- an HTML line comment
+ * </pre>
+ */
 class LineComment extends @linecomment, Comment { }
 
-/** An HTML comment start/end token interpreted as a line comment. */
+/**
+ * An HTML comment start/end token interpreted as a line comment.
+ *
+ * Example:
+ *
+ * ```
+ * &lt;!-- an HTML line comment
+ * --> also an HTML line comment
+ * ```
+ */
 class HtmlLineComment extends @htmlcomment, LineComment { }
 
-/** An HTML comment start token interpreted as a line comment. */
+/**
+ * An HTML comment start token interpreted as a line comment.
+ *
+ * Example:
+ *
+ * ```
+ * &lt;!-- an HTML line comment
+ * ```
+ */
 class HtmlCommentStart extends @htmlcommentstart, HtmlLineComment { }
 
-/** An HTML comment end token interpreted as a line comment. */
+/**
+ * An HTML comment end token interpreted as a line comment.
+ *
+ * Example:
+ *
+ * ```
+ * --> also an HTML line comment
+ * ```
+ */
 class HtmlCommentEnd extends @htmlcommentend, HtmlLineComment { }
 
-/** A `//` comment. */
+/**
+ * A `//` comment.
+ *
+ * Example:
+ *
+ * ```
+ * // a line comment
+ * ```
+ */
 class SlashSlashComment extends @slashslashcomment, LineComment { }
 
-/** A block comment (which may be a JSDoc comment). */
+/**
+ * A block comment (which may be a JSDoc comment).
+ *
+ * Examples:
+ *
+ * <pre>
+ * /* a block comment
+ *   (but not a JSDoc comment) *&#47;
+ * /** a JSDoc comment *&#47;
+ * </pre>
+ */
 class BlockComment extends @blockcomment, Comment { }
 
-/** A C-style block comment which is not a JSDoc comment. */
+/**
+ * A C-style block comment which is not a JSDoc comment.
+ *
+ * Example:
+ *
+ * <pre>
+ * /* a block comment
+ *   (but not a JSDoc comment) *&#47;
+ * </pre>
+ */
 class SlashStarComment extends @slashstarcomment, BlockComment { }
 
-/** A JSDoc comment. */
+/**
+ * A JSDoc comment.
+ *
+ * Example:
+ *
+ * <pre>
+ * /** a JSDoc comment *&#47;
+ * </pre>
+ */
 class DocComment extends @doccomment, BlockComment { }

javascript/ql/src/semmle/javascript/E4X.qll

@@ -7,12 +7,25 @@ import javascript
 module E4X {
   /**
    * An E4X wildcard pseudo-identifier.
+   *
+   * Example:
+   *
+   * ```
+   * *
+   * ```
    */
   class XMLAnyName extends Expr, @e4x_xml_anyname {
   }
 
   /**
-   * An E4X qualified identifier of the form `q::n` or `q::[expr]`.
+   * An E4X qualified identifier.
+   *
+   * Examples:
+   *
+   * ```
+   * soap::encodingStyle
+   * soap::["encodingStyle"]
+   * ```
    *
    * Note that qualified identifiers are not currently supported by the parser, so snapshots
    * will not usually contain any.
@@ -43,7 +56,14 @@ module E4X {
   }
 
   /**
-   * An E4X attribute selector of the form `@name` or `@[expr]`.
+   * An E4X attribute selector.
+   *
+   * Examples:
+   *
+   * ```
+   * @border
+   * @[p]
+   * ```
    */
   class XMLAttributeSelector extends Expr, @e4x_xml_attribute_selector {
     /**
@@ -65,7 +85,13 @@ module E4X {
   }
 
   /**
-   * An E4X filter expression of the form `left.(right)`.
+   * An E4X filter expression.
+   *
+   * Example:
+   *
+   * ```
+   * employees.(@id == 0 || @id == 1)
+   * ```
    */
   class XMLFilterExpression extends Expr, @e4x_xml_filter_expression {
     /**
@@ -84,7 +110,13 @@ module E4X {
   }
 
   /**
-   * An E4X "dot-dot" expression of the form `e..id`.
+   * An E4X "dot-dot" expression.
+   *
+   * Example:
+   *
+   * ```
+   * e..name
+   * ```
    */
   class XMLDotDotExpression extends Expr, @e4x_xml_dotdotexpr {
     /**

javascript/ql/src/semmle/javascript/Functions.qll

@@ -2,7 +2,40 @@
 
 import javascript
 
-/** A function as defined either by a function declaration or a function expression. */
+/**
+ * A function as defined either by a function declaration or a function expression.
+ *
+ * Examples:
+ *
+ * ```
+ * function greet() {         // function declaration
+ *   console.log("Hi");
+ * }
+ *
+ * var greet =
+ *   function() {             // function expression
+ *     console.log("Hi");
+ *   };
+ *
+ * var greet2 =
+ *   () => console.log("Hi")  // arrow function expression
+ *
+ * var o = {
+ *   m() {                    // function expression in a method definition in an object literal
+ *     return 0;
+ *   },
+ *   get x() {                // function expression in a getter method definition in an object literal
+ *     return 1
+ *   }
+ * };
+ *
+ * class C {
+ *   m() {                    // function expression in a method definition in a class
+ *     return 0;
+ *   }
+ * }
+ * ```
+ */
 class Function extends @function, Parameterized, TypeParameterized, StmtContainer, Documentable,
   AST::ValueNode {
   /** Gets the `i`th parameter of this function. */
@@ -472,6 +505,22 @@ private module LinesOfComments {
 
 /**
  * A method defined in a class or object expression.
+ *
+ * Examples:
+ *
+ * ```
+ * var o = {
+ *   m() {          // method defined in an object expression
+ *     return 0;
+ *   }
+ * };
+ *
+ * class C {
+ *   m() {          // method defined in a class
+ *     return 0;
+ *   }
+ * }
+ * ```
  */
 class Method extends FunctionExpr {
   Method() {
@@ -483,6 +532,16 @@ class Method extends FunctionExpr {
 
 /**
  * A constructor defined in a class.
+ *
+ * Example:
+ *
+ * ```
+ * class Point {
+ *   constructor(x, y) {  // constructor
+ *     this.x = x;
+ *     this.y = y;
+ *   }
+ * }
  */
 class Constructor extends FunctionExpr {
   Constructor() { exists(ConstructorDeclaration cd | this = cd.getBody()) }

javascript/ql/src/semmle/javascript/HTML.qll

@@ -11,7 +11,13 @@ module HTML {
   }
 
   /**
-   * An HTML element like `<a href="semmle.com">Semmle</a>`.
+   * An HTML element.
+   *
+   * Example:
+   *
+   * ```
+   * <a href="semmle.com">Semmle</a>
+   * ```
    */
   class Element extends Locatable, @xmlelement {
     Element() { exists(HtmlFile f | xmlElements(this, _, _, _, f)) }
@@ -79,8 +85,14 @@ module HTML {
   /**
    * An attribute of an HTML element.
    *
-   * For example, the element `<a href ="semmle.com" target=_blank>Semmle</a>`
-   * has two attributes: `href ="semmle.com"` and `target=_blank`.
+   * Examples:
+   *
+   * ```
+   * <a
+   *   href ="semmle.com"  <!-- an attribute -->
+   *   target=_blank       <!-- also an attribute -->
+   * >Semmle</a>
+   * ```
    */
   class Attribute extends Locatable, @xmlattribute {
     Attribute() { exists(HtmlFile f | xmlAttrs(this, _, _, _, _, f)) }
@@ -116,13 +128,29 @@ module HTML {
 
   /**
    * An HTML `<html>` element.
+   *
+   * Example:
+   *
+   * ```
+   * <html>
+   * <body>
+   * This is a test.
+   * </body>
+   * </html>
+   * ```
    */
   class DocumentElement extends Element {
     DocumentElement() { getName() = "html" }
   }
 
   /**
    * An HTML `<script>` element.
+   *
+   * Example:
+   *
+   * ```
+   * <script src="https://code.jquery.com/jquery-3.4.1.js"></script>
+   * ```
    */
   class ScriptElement extends Element {
     ScriptElement() { getName() = "script" }
@@ -222,7 +250,15 @@ module HTML {
   }
 
   /**
-   * An HTML text node like `<div>this-is-the-node</div>`.
+   * An HTML text node.
+   *
+   * Example:
+   *
+   * ```
+   * <div>
+   *   This text is represented as a text node.
+   * </div>
+   * ```
    *
    * Note that instances of this class are only available if extraction is done with `--html all` or `--experimental`.
    */
@@ -257,7 +293,13 @@ module HTML {
   }
 
   /**
-   * An HTML comment like <code>&lt;!&hyphen;&hyphen; this &hyphen;&hyphen;&gt;</code>.
+   * An HTML comment.
+   *
+   * Example:
+   *
+   * ```
+   * <!-- this is a comment -->
+   * ```
    */
   class CommentNode extends Locatable, @xmlcomment {
     CommentNode() { exists(HtmlFile f | xmlComments(this, _, _, f)) }