From ae0754602610b587777ba930c17681c389dbfaca Mon Sep 17 00:00:00 2001
From: Max Schaefer <max@semmle.com>
Date: Wed, 17 Jul 2019 10:06:57 +0100
Subject: [PATCH] JavaScript: Add syntax examples to `Comments.qll`, `E4X.qll`,
 `Functions.qll`, `HTML.qll` and `NodeJS.qll`.

---
 .../ql/src/semmle/javascript/Comments.qll     | 98 +++++++++++++++++--
 javascript/ql/src/semmle/javascript/E4X.qll   | 40 +++++++-
 .../ql/src/semmle/javascript/Functions.qll    | 61 +++++++++++-
 javascript/ql/src/semmle/javascript/HTML.qll  | 52 +++++++++-
 .../ql/src/semmle/javascript/NodeJS.qll       | 24 ++++-
 5 files changed, 255 insertions(+), 20 deletions(-)

diff --git a/javascript/ql/src/semmle/javascript/Comments.qll b/javascript/ql/src/semmle/javascript/Comments.qll
index e9e8ed89cc9..fcb8c3e0c88 100644
--- a/javascript/ql/src/semmle/javascript/Comments.qll
+++ b/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 { }
diff --git a/javascript/ql/src/semmle/javascript/E4X.qll b/javascript/ql/src/semmle/javascript/E4X.qll
index df7a151be20..72d9c1f8ae2 100644
--- a/javascript/ql/src/semmle/javascript/E4X.qll
+++ b/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 {
     /**
diff --git a/javascript/ql/src/semmle/javascript/Functions.qll b/javascript/ql/src/semmle/javascript/Functions.qll
index 674464ea9d9..39b23cb52cb 100644
--- a/javascript/ql/src/semmle/javascript/Functions.qll
+++ b/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()) }
diff --git a/javascript/ql/src/semmle/javascript/HTML.qll b/javascript/ql/src/semmle/javascript/HTML.qll
index d0cd379a992..c8418066b49 100644
--- a/javascript/ql/src/semmle/javascript/HTML.qll
+++ b/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,6 +128,16 @@ module HTML {
 
   /**
    * An HTML `<html>` element.
+   *
+   * Example:
+   *
+   * ```
+   * <html>
+   * <body>
+   * This is a test.
+   * </body>
+   * </html>
+   * ```
    */
   class DocumentElement extends Element {
     DocumentElement() { getName() = "html" }
@@ -123,6 +145,12 @@ module 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)) }
diff --git a/javascript/ql/src/semmle/javascript/NodeJS.qll b/javascript/ql/src/semmle/javascript/NodeJS.qll
index de724528334..3259c182758 100644
--- a/javascript/ql/src/semmle/javascript/NodeJS.qll
+++ b/javascript/ql/src/semmle/javascript/NodeJS.qll
@@ -5,6 +5,14 @@ private import NodeModuleResolutionImpl
 
 /**
  * A Node.js module.
+ *
+ * Example:
+ *
+ * ```
+ * const fs = require('fs');
+ * for (var i=2;i<process.argv.length; ++i)
+ *   process.stdout.write(fs.readFileSync(process.argv[i], 'utf8'));
+ * ```
  */
 class NodeModule extends Module {
   NodeModule() {
@@ -146,6 +154,12 @@ private predicate moduleInFile(Module m, File f) { m.getFile() = f }
 
 /**
  * A `require` import.
+ *
+ * Example:
+ *
+ * ```
+ * require('fs')
+ * ```
  */
 class Require extends CallExpr, Import {
   Require() {
@@ -304,7 +318,15 @@ private class JoinedPath extends PathExprInModule, @callexpr {
   }
 }
 
-/** A reference to the special `module` variable. */
+/**
+ * A reference to the special `module` variable.
+ *
+ * Example:
+ *
+ * ```
+ * module
+ * ```
+ */
 class ModuleAccess extends VarAccess {
   ModuleAccess() { exists(ModuleScope ms | this = ms.getVariable("module").getAnAccess()) }
 }