Swift: add and fix some schema.py documentation

Author: redsun82

swift/codegen/templates/ql_class.mustache

@@ -8,12 +8,12 @@ import {{.}}
 module Generated {
   {{#has_doc}}
   /**
-  {{#doc}}
-   * {{.}}
-  {{/doc}}
   {{#ql_internal}}
    * INTERNAL: Do not use.
   {{/ql_internal}}
+  {{#doc}}
+   * {{.}}
+  {{/doc}}
    */
   {{/has_doc}}
   class {{name}} extends Synth::T{{name}}{{#bases}}, {{.}}{{/bases}} {

swift/ql/.generated.list

@@ -363,9 +363,9 @@ ql/lib/codeql/swift/elements/type/VariadicSequenceType.qll 5bca77dd661d3b2653d31
 ql/lib/codeql/swift/elements/type/VariadicSequenceTypeConstructor.qll 0d1d2328a3b5e503a883e7e6d7efd0ca5e7f2633abead9e4c94a9f98ed3cb223 69bff81c1b9413949eacb9298d2efb718ea808e68364569a1090c9878c4af856
 ql/lib/codeql/swift/elements/type/WeakStorageType.qll 87a28616eea3600fb0156fffcd65eeddc1ea74ce9c0ba5886c6365b9359e00ce 9c968414d7cc8d672f3754bced5d4f83f43a6d7872d0d263d79ff60483e1f996
 ql/lib/codeql/swift/elements/type/WeakStorageTypeConstructor.qll d88b031ef44d6de14b3ddcff2eb47b53dbd11550c37250ff2edb42e5d21ec3e9 26d855c33492cf7a118e439f7baeed0e5425cfaf058b1dcc007eca7ed765c897
-ql/lib/codeql/swift/elements.qll 56ea4825f91bb761355f366b0b57ea49cd3df513abf901b370445b0f9264845d 56ea4825f91bb761355f366b0b57ea49cd3df513abf901b370445b0f9264845d
+ql/lib/codeql/swift/elements.qll f1a8645f3aaad53cfe653b5b93a9dbc8c1a9fce48d0804d876f79fa01b877924 f1a8645f3aaad53cfe653b5b93a9dbc8c1a9fce48d0804d876f79fa01b877924
 ql/lib/codeql/swift/generated/AstNode.qll 02ca56d82801f942ae6265c6079d92ccafdf6b532f6bcebd98a04029ddf696e4 6216fda240e45bd4302fa0cf0f08f5f945418b144659264cdda84622b0420aa2
-ql/lib/codeql/swift/generated/Callable.qll cdadcd29460e9c956b494bde46671f673abd39c91cee4acc8b1cde55afb5e4d4 373904ff78518af88fc1578e830552c157ecdbba2f913aefce7e7b7656111a6e
+ql/lib/codeql/swift/generated/Callable.qll cc67625a86b62f91d1480e284a946aa5274a21a7da03d7ad9f1dc2197927d394 7ee41be3d36c74ed5662d7c1babe591942429f87020d09d7ba2c447ba058fb0a
 ql/lib/codeql/swift/generated/Comment.qll f58b49f6e68c21f87c51e2ff84c8a64b09286d733e86f70d67d3a98fe6260bd6 975bbb599a2a7adc35179f6ae06d9cbc56ea8a03b972ef2ee87604834bc6deb1
 ql/lib/codeql/swift/generated/DbFile.qll a49b2a2cb2788cb49c861ebcd458b8daead7b15adb19c3a9f4db3bf39a0051fc a49b2a2cb2788cb49c861ebcd458b8daead7b15adb19c3a9f4db3bf39a0051fc
 ql/lib/codeql/swift/generated/DbLocation.qll b9baea963d9fa82068986512c0649d1050897654eee3df51dba17cf6b1170873 b9baea963d9fa82068986512c0649d1050897654eee3df51dba17cf6b1170873
@@ -414,7 +414,7 @@ ql/lib/codeql/swift/generated/decl/OperatorDecl.qll 3ffdc7ab780ee94a975f0ce3ae42
 ql/lib/codeql/swift/generated/decl/ParamDecl.qll f182ebac3c54a57a291d695b87ff3dbc1499ea699747b800dc4a8c1a5a4524b1 979e27a6ce2bc932a45b968ee2f556afe1071888f1de8dd8ead60fb11acf300c
 ql/lib/codeql/swift/generated/decl/PatternBindingDecl.qll 15a43e1b80fc6ef571e726ab13c7cd3f308d6be1d28bcb175e8b5971d646da7c 1b2e19d6fdd5a89ce9be9489fef5dc6ba4390249195fe41f53848be733c62a39
 ql/lib/codeql/swift/generated/decl/PostfixOperatorDecl.qll 5aa85fa325020b39769fdb18ef97ef63bd28e0d46f26c1383138221a63065083 5aa85fa325020b39769fdb18ef97ef63bd28e0d46f26c1383138221a63065083
-ql/lib/codeql/swift/generated/decl/PoundDiagnosticDecl.qll c5a646d7b82c97b97d8c79855fc68d36ca494d81dfc83582131d0551187a9b77 a2c567589a89bda3de916d9c5111b123136f03239bb40ac71ac5e949f9b527ce
+ql/lib/codeql/swift/generated/decl/PoundDiagnosticDecl.qll 1004b329281d0de9d1cc315c73d5886b0dc8afecb344c9d648d887d1da7cfd1d b90e249a42a8baded3632828d380f158e475f0765356a2b70e49082adedd3ba7
 ql/lib/codeql/swift/generated/decl/PrecedenceGroupDecl.qll d0918f238484052a0af902624b671c04eb8d018ee71ef4931c2fdbb74fa5c5d4 d0918f238484052a0af902624b671c04eb8d018ee71ef4931c2fdbb74fa5c5d4
 ql/lib/codeql/swift/generated/decl/PrefixOperatorDecl.qll 18f2a1f83ea880775344fbc57ed332e17edba97a56594da64580baeb45e95a5d 18f2a1f83ea880775344fbc57ed332e17edba97a56594da64580baeb45e95a5d
 ql/lib/codeql/swift/generated/decl/ProtocolDecl.qll 4b03e3c2a7af66e66e8abc40bd2ea35e71959f471669e551f4c42af7f0fd4566 4b03e3c2a7af66e66e8abc40bd2ea35e71959f471669e551f4c42af7f0fd4566
@@ -424,7 +424,7 @@ ql/lib/codeql/swift/generated/decl/TopLevelCodeDecl.qll aececf62fda517bd90b1c56b
 ql/lib/codeql/swift/generated/decl/TypeAliasDecl.qll 15cb5bdbe9d722c403874f744bfb3da85f532e33638a64a593acbbdee2f6095e 15cb5bdbe9d722c403874f744bfb3da85f532e33638a64a593acbbdee2f6095e
 ql/lib/codeql/swift/generated/decl/TypeDecl.qll 74bb5f0fe2648d95c84fdce804740f2bba5c7671e15cbea671d8509456bf5c2b 32bc7154c8585c25f27a3587bb4ba039c8d69f09d945725e45d730de44f7a5ae
 ql/lib/codeql/swift/generated/decl/ValueDecl.qll 7b4e4c9334be676f242857c77099306d8a0a4357b253f8bc68f71328cedf1f58 f18938c47f670f2e0c27ffd7e31e55f291f88fb50d8e576fcea116d5f9e5c66d
-ql/lib/codeql/swift/generated/decl/VarDecl.qll 2fca00ba8b535d7cefc2fa863246a0821437ca29b885c4c30362e8a63f284479 5ba623001e071c16267e94d050bfd973addf2436152c7726945b5d87aa521af8
+ql/lib/codeql/swift/generated/decl/VarDecl.qll bdea76fe6c8f721bae52bbc26a2fc1cbd665a19a6920b36097822839158d9d3b 9c91d8159fd7a53cba479d8c8f31f49ad2b1e2617b8cd9e7d1a2cb4796dfa2da
 ql/lib/codeql/swift/generated/expr/AbiSafeConversionExpr.qll f4c913df3f1c139a0533f9a3a2f2e07aee96ab723c957fc7153d68564e4fdd6d f4c913df3f1c139a0533f9a3a2f2e07aee96ab723c957fc7153d68564e4fdd6d
 ql/lib/codeql/swift/generated/expr/AbstractClosureExpr.qll f0060c2972d2e1f9818d8deea3ceebbbe0b19d2ce11adc9b670beb672c4564d3 5f2500c5f3728f81599bd4e1fb9c97ac5a44a6dce8c1ab84a850c62aae3741ff
 ql/lib/codeql/swift/generated/expr/AnyHashableErasureExpr.qll f450ac8e316def1cd64dcb61411bae191144079df7f313a5973e59dc89fe367f f450ac8e316def1cd64dcb61411bae191144079df7f313a5973e59dc89fe367f
@@ -527,7 +527,7 @@ ql/lib/codeql/swift/generated/expr/PropertyWrapperValuePlaceholderExpr.qll 01189
 ql/lib/codeql/swift/generated/expr/ProtocolMetatypeToObjectExpr.qll b692be6e5b249c095b77f4adcad5760f48bc07f6f53767ee3d236025ee4a2a51 cc69abe3cde83a4cd398ce666509326b21e7ee0b4b766c8dc0e0fea0c7d1ca91
 ql/lib/codeql/swift/generated/expr/RebindSelfInConstructorExpr.qll 7796a88c1635b3bd2492563880c995f1a7a0c68f69bad33b8bd77086eb1ce404 aee11e030ba21115931cbc1e34ac001eaafe4460fb3724a078aa4cbda84e4642
 ql/lib/codeql/swift/generated/expr/RegexLiteralExpr.qll ed7eccdf051b18a6388c47986b68e755edfae5d81d83e58772effb72c0e9d75e ed7eccdf051b18a6388c47986b68e755edfae5d81d83e58772effb72c0e9d75e
-ql/lib/codeql/swift/generated/expr/SelfApplyExpr.qll c676c551bcb528512dad6422cce39be8391d03f517df2d5dc4d6ac7ab4f23897 64b3ddb7e2b093acca289d5e81d4662560d8aef20d4dd07fcd41771d54fb3f5c
+ql/lib/codeql/swift/generated/expr/SelfApplyExpr.qll 8a2d8ee8d0006a519aadbdb9055cfb58a28fd2837f4e3641b357e3b6bda0febe fc64b664b041e57f9ca10d94c59e9723a18d4ff9d70f2389f4c11a2a9f903a6f
 ql/lib/codeql/swift/generated/expr/SequenceExpr.qll 45f976cbc3ce6b3278955a76a55cd0769e69f9bd16e84b40888cd8ebda6be917 ebb090897e4cc4371383aa6771163f73fa2c28f91e6b5f4eed42d7ad018267f3
 ql/lib/codeql/swift/generated/expr/StringLiteralExpr.qll f420c5cd51a223b6f98177147967266e0094a5718ba2d57ae2d3acbb64bbb4b6 30d6dab2a93fd95e652a700902c4d106fecfce13880c2ece565de29f2504bedf
 ql/lib/codeql/swift/generated/expr/StringToPointerExpr.qll ef69b570aa90697d438f5787a86797955b4b2f985960b5859a7bd13b9ecb9cd3 ef69b570aa90697d438f5787a86797955b4b2f985960b5859a7bd13b9ecb9cd3

swift/ql/lib/codeql/swift/elements.qll

@@ -157,7 +157,6 @@ import codeql.swift.elements.expr.PropertyWrapperValuePlaceholderExpr
 import codeql.swift.elements.expr.ProtocolMetatypeToObjectExpr
 import codeql.swift.elements.expr.RebindSelfInConstructorExpr
 import codeql.swift.elements.expr.RegexLiteralExpr
-import codeql.swift.elements.expr.SelfApplyExpr
 import codeql.swift.elements.expr.SequenceExpr
 import codeql.swift.elements.expr.StringLiteralExpr
 import codeql.swift.elements.expr.StringToPointerExpr

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

@@ -8,7 +8,7 @@ import codeql.swift.elements.decl.ParamDecl
 module Generated {
   class Callable extends Synth::TCallable, Element {
     /**
-     * Gets the name of this Callable, if it exists.
+     * Gets the name of this callable, if it exists.
      */
     string getName() { result = Synth::convertCallableToRaw(this).(Raw::Callable).getName() }
 

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

@@ -12,7 +12,9 @@ module Generated {
     override string getAPrimaryQlClass() { result = "PoundDiagnosticDecl" }
 
     /**
-     * Gets the This is 1 for `#error` and 2 for `#warning`.
+     * Gets the kind of this pound diagnostic declaration.
+     *
+     * This is 1 for `#error` and 2 for `#warning`.
      */
     int getKind() {
       result = Synth::convertPoundDiagnosticDeclToRaw(this).(Raw::PoundDiagnosticDecl).getKind()

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

@@ -8,6 +8,24 @@ import codeql.swift.elements.decl.PatternBindingDecl
 import codeql.swift.elements.type.Type
 
 module Generated {
+  /**
+   * A declaration of a variable such as
+   * * a local variable in a function:
+   * ```
+   * func foo() {
+   *   var x = 42  // <-
+   *   let y = "hello"  // <-
+   *   ...
+   * }
+   * ```
+   * * a member of a `struct` or `class`:
+   * ```
+   * struct S {
+   *   var size : Int  // <-
+   * }
+   * ```
+   * * ...
+   */
   class VarDecl extends Synth::TVarDecl, AbstractStorageDecl {
     /**
      * Gets the name of this variable declaration.
@@ -117,7 +135,7 @@ module Generated {
      * Gets the property wrapper backing variable binding of this variable declaration, if it exists.
      *
      * This is the synthesized binding introducing the property wrapper backing variable for this
-     * variable, if any.
+     * variable, if any. See `getPropertyWrapperBackingVar`.
      */
     final PatternBindingDecl getPropertyWrapperBackingVarBinding() {
       result = getImmediatePropertyWrapperBackingVarBinding().resolve()
@@ -146,7 +164,21 @@ module Generated {
     /**
      * Gets the property wrapper backing variable of this variable declaration, if it exists.
      *
-     * This is the synthesized variable holding the property wrapper for this variable, if any.
+     * This is the compiler synthesized variable holding the property wrapper for this variable, if any.
+     *
+     * For a property wrapper like
+     * ```
+     * @propertyWrapper struct MyWrapper { ... }
+     *
+     * struct S {
+     *   @MyWrapper var x : Int = 42
+     * }
+     * ```
+     * the compiler synthesizes a variable in `S` along the lines of
+     * ```
+     *   var _x = MyWrapper(wrappedValue: 42)
+     * ```
+     * This predicate returns such variable declaration.
      */
     final VarDecl getPropertyWrapperBackingVar() {
       result = getImmediatePropertyWrapperBackingVar().resolve()
@@ -174,7 +206,7 @@ module Generated {
      * Gets the property wrapper projection variable binding of this variable declaration, if it exists.
      *
      * This is the synthesized binding introducing the property wrapper projection variable for this
-     * variable, if any.
+     * variable, if any. See `getPropertyWrapperProjectionVar`.
      */
     final PatternBindingDecl getPropertyWrapperProjectionVarBinding() {
       result = getImmediatePropertyWrapperProjectionVarBinding().resolve()
@@ -206,6 +238,24 @@ module Generated {
      * If this variable has a property wrapper with a projected value, this is the corresponding
      * synthesized variable holding that projected value, accessible with this variable's name
      * prefixed with `$`.
+     *
+     * For a property wrapper like
+     * ```
+     * @propertyWrapper struct MyWrapper {
+     *   var projectedValue : Bool
+     *   ...
+     * }
+     *
+     * struct S {
+     *   @MyWrapper var x : Int = 42
+     * }
+     * ```
+     * ```
+     * the compiler synthesizes a variable in `S` along the lines of
+     * ```
+     *   var $x : Bool { ... }
+     * ```
+     * This predicate returns such variable declaration.
      */
     final VarDecl getPropertyWrapperProjectionVar() {
       result = getImmediatePropertyWrapperProjectionVar().resolve()

swift/ql/lib/codeql/swift/generated/expr/SelfApplyExpr.qll

@@ -5,6 +5,11 @@ import codeql.swift.elements.expr.ApplyExpr
 import codeql.swift.elements.expr.Expr
 
 module Generated {
+  /**
+   * INTERNAL: Do not use.
+   * An internal raw instance of method lookups like `x.foo` in `x.foo()`.
+   * This is completely replaced by the synthesized type `MethodLookupExpr`.
+   */
   class SelfApplyExpr extends Synth::TSelfApplyExpr, ApplyExpr {
     /**
      * Gets the base of this self apply expression.

swift/schema.py

@@ -128,7 +128,7 @@ class PatternBindingDecl(Decl):
 
 class PoundDiagnosticDecl(Decl):
     """ A diagnostic directive, which is either `#error` or `#warning`."""
-    kind: int | doc("""This is 1 for `#error` and 2 for `#warning`""")
+    kind: int | desc("""This is 1 for `#error` and 2 for `#warning`.""")
     message: "StringLiteralExpr" | child
 
 class PrecedenceGroupDecl(Decl):
@@ -144,26 +144,76 @@ class AbstractStorageDecl(ValueDecl):
     accessor_decls: list["AccessorDecl"] | child
 
 class VarDecl(AbstractStorageDecl):
+    """
+    A declaration of a variable such as
+    * a local variable in a function:
+    ```
+    func foo() {
+      var x = 42  // <-
+      let y = "hello"  // <-
+      ...
+    }
+    ```
+    * a member of a `struct` or `class`:
+    ```
+    struct S {
+      var size : Int  // <-
+    }
+    ```
+    * ...
+    """
     name: string
     type: Type
     attached_property_wrapper_type: optional[Type]
     parent_pattern: optional[Pattern]
     parent_initializer: optional[Expr]
     property_wrapper_backing_var_binding: optional[PatternBindingDecl] | child | desc("""
         This is the synthesized binding introducing the property wrapper backing variable for this
-        variable, if any.
+        variable, if any. See `getPropertyWrapperBackingVar`.
     """)
     property_wrapper_backing_var: optional["VarDecl"] | child | desc("""
-        This is the synthesized variable holding the property wrapper for this variable, if any.
+        This is the compiler synthesized variable holding the property wrapper for this variable, if any.
+
+        For a property wrapper like
+        ```
+        @propertyWrapper struct MyWrapper { ... }
+
+        struct S {
+          @MyWrapper var x : Int = 42
+        }
+        ```
+        the compiler synthesizes a variable in `S` along the lines of
+        ```
+          var _x = MyWrapper(wrappedValue: 42)
+        ```
+        This predicate returns such variable declaration.
     """)
     property_wrapper_projection_var_binding: optional[PatternBindingDecl] | child | desc("""
         This is the synthesized binding introducing the property wrapper projection variable for this
-        variable, if any.
+        variable, if any. See `getPropertyWrapperProjectionVar`.
     """)
     property_wrapper_projection_var: optional["VarDecl"] | child | desc("""
         If this variable has a property wrapper with a projected value, this is the corresponding
         synthesized variable holding that projected value, accessible with this variable's name
         prefixed with `$`.
+
+        For a property wrapper like
+        ```
+        @propertyWrapper struct MyWrapper {
+          var projectedValue : Bool
+          ...
+        }
+
+        struct S {
+          @MyWrapper var x : Int = 42
+        }
+        ```
+        ```
+        the compiler synthesizes a variable in `S` along the lines of
+        ```
+          var $x : Bool { ... }
+        ```
+        This predicate returns such variable declaration.
     """)
 
 class ParamDecl(VarDecl):
@@ -178,7 +228,7 @@ class ParamDecl(VarDecl):
     """)
 
 class Callable(Element):
-    name: optional[string] | doc("name of this Callable")
+    name: optional[string] | doc("name of this callable")
     self_param: optional[ParamDecl] | child
     params: list[ParamDecl] | child
     body: optional["BraceStmt"] | child | desc("The body is absent within protocol declarations.")
@@ -639,7 +689,12 @@ class ProtocolMetatypeToObjectExpr(ImplicitConversionExpr):
 class RegexLiteralExpr(LiteralExpr):
     pass
 
+@ql.internal
 class SelfApplyExpr(ApplyExpr):
+    """
+    An internal raw instance of method lookups like `x.foo` in `x.foo()`.
+    This is completely replaced by the synthesized type `MethodLookupExpr`.
+    """
     base: Expr
 
 class StringToPointerExpr(ImplicitConversionExpr):