Merge pull request #286 from microsoft/powershell-add-qldoc

PS: Add QLDoc to a bunch of public AST classes

Author: MathiasVP

powershell/ql/lib/semmle/code/powershell/ast/internal/ArrayExpression.qll

@@ -1,5 +1,19 @@
 private import AstImport
 
+/**
+ * An array expression. For example:
+ * ```
+ * $myArray = @("text", 42, $true)
+ * ```
+ * 
+ * An array expression is an expression of the form `@(...)` where `...` is
+ * a `StmtBlock` that computes the elements of the array. Often, that
+ * `StmtBlock` is an `ArrayLiteral`, but that is not necessarily the case. For
+ * example in:
+ * ```
+ * $squares = @(foreach ($n in 1..5) { $n * $n })
+ * ```
+ */
 class ArrayExpr extends Expr, TArrayExpr {
   StmtBlock getStmtBlock() {
     exists(Raw::Ast r | r = getRawAst(this) |

powershell/ql/lib/semmle/code/powershell/ast/internal/ArrayLiteral.qll

@@ -1,5 +1,11 @@
 private import AstImport
 
+/**
+ * An array literal. For example:
+ * ```
+ * 1, 2, 3, 4
+ * ```
+ */
 class ArrayLiteral extends Expr, TArrayLiteral {
   Expr getExpr(int index) {
     exists(ChildIndex i, Raw::Ast r | i = arrayLiteralExpr(index) and r = getRawAst(this) |

powershell/ql/lib/semmle/code/powershell/ast/internal/AssignmentStatement.qll

@@ -1,5 +1,11 @@
 private import AstImport
 
+/**
+ * An assignment statement. For example:
+ * ```
+ * $name = "John"
+ * ```
+ */
 class AssignStmt extends Stmt, TAssignStmt {
   Expr getRightHandSide() {
     exists(Raw::Ast r | r = getRawAst(this) |

powershell/ql/lib/semmle/code/powershell/ast/internal/Ast.qll

@@ -1,5 +1,10 @@
 private import AstImport
 
+/**
+ * A PowerShell AST (Abstract Syntax Tree) element.
+ * 
+ * This is the root of the PowerShell AST class hierarchy.
+ */
 class Ast extends TAst {
   string toString() { none() }
 

powershell/ql/lib/semmle/code/powershell/ast/internal/AutomaticVariable.qll

@@ -1,5 +1,8 @@
 private import AstImport
 
+/**
+ * A PowerShell automatic variable (for example, `$PSVersionTable` or `$MyInvocation`).
+ */
 class AutomaticVariable extends Expr, TAutomaticVariable {
   final override string toString() { result = this.getLowerCaseName() }