Swift: add auto-generated docs for getters

Author: redsun82

swift/codegen/templates/ql_class.mustache

@@ -14,15 +14,38 @@ module Generated {
    */
   {{/has_doc}}
   class {{name}} extends Synth::T{{name}}{{#bases}}, {{.}}{{/bases}} {
-    {{#root}}
+  {{#root}}
+    /**
+     * Gets the string representation of this element.
+     */
     string toString() { none() } // overridden by subclasses
 
+    /**
+     * Gets the name of a primary CodeQL class to which this element belongs.
+     *
+     * This is the most precise syntactic category to which they belong; for
+     * example, `CallExpr` is a primary class, but `ApplyExpr` is not.
+     *
+     * There might be some corner cases when this returns multiple classes, or none.
+     */
     string getAPrimaryQlClass() { none() } // overridden by subclasses
 
+    /**
+     * Gets a comma-separated list of the names of the primary CodeQL classes to which this element belongs.
+     */
     final string getPrimaryQlClasses() { result = concat(this.getAPrimaryQlClass(), ",") }
 
+    /**
+     * Gets the most immediate element that should substitute this element in the explicit AST, if any.
+     * Classes can override this to indicate this node should be in the "hidden" AST, mostly reserved
+     * for conversions and syntactic sugar nodes like parentheses.
+     */
     {{name}} getResolveStep() { none() } // overridden by subclasses
 
+    /**
+     * Gets the element that should substitute this element in the explicit AST, applying `getResolveStep`
+     * transitively.
+     */
     final {{name}} resolve() {
       not exists(getResolveStep()) and result = this
       or
@@ -35,6 +58,10 @@ module Generated {
     {{#properties}}
 
     {{#type_is_class}}
+    /**
+     * Gets the {{#is_repeated}}`index`th {{/is_repeated}}{{doc_name}}{{#is_optional}}, if it exists{{/is_optional}}.
+     * This is taken from the "hidden" AST and should only be used to be overridden by classes.
+     */
     {{type}} getImmediate{{singular}}({{#is_repeated}}int index{{/is_repeated}}) {
       {{^ipa}}
       result = Synth::convert{{type}}FromRaw(Synth::convert{{name}}ToRaw(this){{^root}}.(Raw::{{name}}){{/root}}.{{getter}}({{#is_repeated}}index{{/is_repeated}}))
@@ -44,12 +71,41 @@ module Generated {
       {{/ipa}}
     }
 
+    /**
+     * Gets the {{#is_repeated}}`index`th {{/is_repeated}}{{doc_name}}{{#is_optional}}, if it exists{{/is_optional}}.
+    {{#has_doc}}
+     *
+    {{#doc}}
+     * {{.}}
+    {{/doc}}
+    {{/has_doc}}
+     */
     final {{type}} {{getter}}({{#is_repeated}}int index{{/is_repeated}}) {
       result = getImmediate{{singular}}({{#is_repeated}}index{{/is_repeated}}).resolve()
     }
 
     {{/type_is_class}}
     {{^type_is_class}}
+    {{^is_predicate}}
+    /**
+     * Gets the {{#is_repeated}}`index`th {{/is_repeated}}{{doc_name}}{{#is_optional}}, if it exists{{/is_optional}}.
+    {{#has_doc}}
+     *
+    {{#doc}}
+     * {{.}}
+    {{/doc}}
+    {{/has_doc}}
+     */
+    {{/is_predicate}}
+    {{#is_predicate}}
+    {{#has_doc}}
+    /**
+    {{#doc}}
+     * {{.}}
+    {{/doc}}
+     */
+    {{/has_doc}}
+    {{/is_predicate}}
     {{type}} {{getter}}({{#is_repeated}}int index{{/is_repeated}}) {
       {{^ipa}}
       {{^is_predicate}}result = {{/is_predicate}}Synth::convert{{name}}ToRaw(this){{^root}}.(Raw::{{name}}){{/root}}.{{getter}}({{#is_repeated}}index{{/is_repeated}})
@@ -61,17 +117,26 @@ module Generated {
 
     {{/type_is_class}}
     {{#is_optional}}
+    /**
+     * Holds if `{{getter}}({{#is_repeated}}index{{/is_repeated}})` exists.
+     */
     final predicate has{{singular}}({{#is_repeated}}int index{{/is_repeated}}) {
       exists({{getter}}({{#is_repeated}}index{{/is_repeated}}))
     }
     {{/is_optional}}
     {{#is_repeated}}
 
+    /**
+     * Gets any of the {{doc_name_plural}}.
+     */
     final {{type}} {{indefinite_getter}}() {
       result = {{getter}}(_)
     }
     {{^is_optional}}
 
+    /**
+     * Gets the number of {{doc_name_plural}}.
+     */
     final int getNumberOf{{plural}}() {
       result = count({{indefinite_getter}}())
     }

swift/ql/lib/codeql/swift/generated/Callable.qll

@@ -7,37 +7,70 @@ import codeql.swift.elements.decl.ParamDecl
 
 module Generated {
   class Callable extends Synth::TCallable, Element {
+    /**
+     * Gets the self param, if it exists.
+     * This is taken from the "hidden" AST and should only be used to be overridden by classes.
+     */
     ParamDecl getImmediateSelfParam() {
       result =
         Synth::convertParamDeclFromRaw(Synth::convertCallableToRaw(this)
               .(Raw::Callable)
               .getSelfParam())
     }
 
+    /**
+     * Gets the self param, if it exists.
+     */
     final ParamDecl getSelfParam() { result = getImmediateSelfParam().resolve() }
 
+    /**
+     * Holds if `getSelfParam()` exists.
+     */
     final predicate hasSelfParam() { exists(getSelfParam()) }
 
+    /**
+     * Gets the `index`th param.
+     * This is taken from the "hidden" AST and should only be used to be overridden by classes.
+     */
     ParamDecl getImmediateParam(int index) {
       result =
         Synth::convertParamDeclFromRaw(Synth::convertCallableToRaw(this)
               .(Raw::Callable)
               .getParam(index))
     }
 
+    /**
+     * Gets the `index`th param.
+     */
     final ParamDecl getParam(int index) { result = getImmediateParam(index).resolve() }
 
+    /**
+     * Gets any of the params.
+     */
     final ParamDecl getAParam() { result = getParam(_) }
 
+    /**
+     * Gets the number of params.
+     */
     final int getNumberOfParams() { result = count(getAParam()) }
 
+    /**
+     * Gets the body, if it exists.
+     * This is taken from the "hidden" AST and should only be used to be overridden by classes.
+     */
     BraceStmt getImmediateBody() {
       result =
         Synth::convertBraceStmtFromRaw(Synth::convertCallableToRaw(this).(Raw::Callable).getBody())
     }
 
+    /**
+     * Gets the body, if it exists.
+     */
     final BraceStmt getBody() { result = getImmediateBody().resolve() }
 
+    /**
+     * Holds if `getBody()` exists.
+     */
     final predicate hasBody() { exists(getBody()) }
   }
 }

swift/ql/lib/codeql/swift/generated/Comment.qll

@@ -7,6 +7,9 @@ module Generated {
   class Comment extends Synth::TComment, Locatable {
     override string getAPrimaryQlClass() { result = "Comment" }
 
+    /**
+     * Gets the text.
+     */
     string getText() { result = Synth::convertCommentToRaw(this).(Raw::Comment).getText() }
   }
 }

swift/ql/lib/codeql/swift/generated/Element.qll

@@ -4,14 +4,37 @@ private import codeql.swift.generated.Raw
 
 module Generated {
   class Element extends Synth::TElement {
+    /**
+     * Gets the string representation of this element.
+     */
     string toString() { none() } // overridden by subclasses
 
+    /**
+     * Gets the name of a primary CodeQL class to which this element belongs.
+     *
+     * This is the most precise syntactic category to which they belong; for
+     * example, `CallExpr` is a primary class, but `ApplyExpr` is not.
+     *
+     * There might be some corner cases when this returns multiple classes, or none.
+     */
     string getAPrimaryQlClass() { none() } // overridden by subclasses
 
+    /**
+     * Gets a comma-separated list of the names of the primary CodeQL classes to which this element belongs.
+     */
     final string getPrimaryQlClasses() { result = concat(this.getAPrimaryQlClass(), ",") }
 
+    /**
+     * Gets the most immediate element that should substitute this element in the explicit AST, if any.
+     * Classes can override this to indicate this node should be in the "hidden" AST, mostly reserved
+     * for conversions and syntactic sugar nodes like parentheses.
+     */
     Element getResolveStep() { none() } // overridden by subclasses
 
+    /**
+     * Gets the element that should substitute this element in the explicit AST, applying `getResolveStep`
+     * transitively.
+     */
     final Element resolve() {
       not exists(getResolveStep()) and result = this
       or

swift/ql/lib/codeql/swift/generated/File.qll

@@ -5,6 +5,9 @@ import codeql.swift.elements.Element
 
 module Generated {
   class File extends Synth::TFile, Element {
+    /**
+     * Gets the name.
+     */
     string getName() { result = Synth::convertFileToRaw(this).(Raw::File).getName() }
   }
 }

swift/ql/lib/codeql/swift/generated/Locatable.qll

@@ -6,15 +6,25 @@ import codeql.swift.elements.Location
 
 module Generated {
   class Locatable extends Synth::TLocatable, Element {
+    /**
+     * Gets the location, if it exists.
+     * This is taken from the "hidden" AST and should only be used to be overridden by classes.
+     */
     Location getImmediateLocation() {
       result =
         Synth::convertLocationFromRaw(Synth::convertLocatableToRaw(this)
               .(Raw::Locatable)
               .getLocation())
     }
 
+    /**
+     * Gets the location, if it exists.
+     */
     final Location getLocation() { result = getImmediateLocation().resolve() }
 
+    /**
+     * Holds if `getLocation()` exists.
+     */
     final predicate hasLocation() { exists(getLocation()) }
   }
 }

swift/ql/lib/codeql/swift/generated/Location.qll

@@ -6,21 +6,40 @@ import codeql.swift.elements.File
 
 module Generated {
   class Location extends Synth::TLocation, Element {
+    /**
+     * Gets the file.
+     * This is taken from the "hidden" AST and should only be used to be overridden by classes.
+     */
     File getImmediateFile() {
       result =
         Synth::convertFileFromRaw(Synth::convertLocationToRaw(this).(Raw::Location).getFile())
     }
 
+    /**
+     * Gets the file.
+     */
     final File getFile() { result = getImmediateFile().resolve() }
 
+    /**
+     * Gets the start line.
+     */
     int getStartLine() { result = Synth::convertLocationToRaw(this).(Raw::Location).getStartLine() }
 
+    /**
+     * Gets the start column.
+     */
     int getStartColumn() {
       result = Synth::convertLocationToRaw(this).(Raw::Location).getStartColumn()
     }
 
+    /**
+     * Gets the end line.
+     */
     int getEndLine() { result = Synth::convertLocationToRaw(this).(Raw::Location).getEndLine() }
 
+    /**
+     * Gets the end column.
+     */
     int getEndColumn() { result = Synth::convertLocationToRaw(this).(Raw::Location).getEndColumn() }
   }
 }

swift/ql/lib/codeql/swift/generated/decl/AbstractFunctionDecl.qll

@@ -8,6 +8,9 @@ import codeql.swift.elements.decl.ValueDecl
 module Generated {
   class AbstractFunctionDecl extends Synth::TAbstractFunctionDecl, GenericContext, ValueDecl,
     Callable {
+    /**
+     * Gets the name.
+     */
     string getName() {
       result = Synth::convertAbstractFunctionDeclToRaw(this).(Raw::AbstractFunctionDecl).getName()
     }

swift/ql/lib/codeql/swift/generated/decl/AbstractStorageDecl.qll

@@ -6,19 +6,32 @@ import codeql.swift.elements.decl.ValueDecl
 
 module Generated {
   class AbstractStorageDecl extends Synth::TAbstractStorageDecl, ValueDecl {
+    /**
+     * Gets the `index`th accessor decl.
+     * This is taken from the "hidden" AST and should only be used to be overridden by classes.
+     */
     AccessorDecl getImmediateAccessorDecl(int index) {
       result =
         Synth::convertAccessorDeclFromRaw(Synth::convertAbstractStorageDeclToRaw(this)
               .(Raw::AbstractStorageDecl)
               .getAccessorDecl(index))
     }
 
+    /**
+     * Gets the `index`th accessor decl.
+     */
     final AccessorDecl getAccessorDecl(int index) {
       result = getImmediateAccessorDecl(index).resolve()
     }
 
+    /**
+     * Gets any of the accessor decls.
+     */
     final AccessorDecl getAnAccessorDecl() { result = getAccessorDecl(_) }
 
+    /**
+     * Gets the number of accessor decls.
+     */
     final int getNumberOfAccessorDecls() { result = count(getAnAccessorDecl()) }
   }
 }

swift/ql/lib/codeql/swift/generated/decl/ConcreteVarDecl.qll

@@ -7,6 +7,9 @@ module Generated {
   class ConcreteVarDecl extends Synth::TConcreteVarDecl, VarDecl {
     override string getAPrimaryQlClass() { result = "ConcreteVarDecl" }
 
+    /**
+     * Gets the introducer int.
+     */
     int getIntroducerInt() {
       result = Synth::convertConcreteVarDeclToRaw(this).(Raw::ConcreteVarDecl).getIntroducerInt()
     }