Merge pull request github#11932 from github/redsun82/swift-docs

redsun82 · web-flow · commit f4cb920624b4 · 2023-01-25T10:52:00.000+01:00
Swift: add and fix some `schema.py` documentation
diff --git a/swift/codegen/generators/qlgen.py b/swift/codegen/generators/qlgen.py
@@ -331,7 +331,12 @@ def generate(opts, renderer):
         renderer.render(ql.ImportList([i for name, i in imports.items() if not classes[name].ql_internal]),
                         include_file)
 
-        renderer.render(ql.GetParentImplementation(list(classes.values())), out / 'ParentChild.qll')
+        renderer.render(
+            ql.GetParentImplementation(
+                classes=list(classes.values()),
+                additional_imports=[i for name, i in imports.items() if classes[name].ql_internal],
+            ),
+            out / 'ParentChild.qll')
 
         for c in data.classes.values():
             if _should_skip_qltest(c, data.classes):
diff --git a/swift/codegen/lib/ql.py b/swift/codegen/lib/ql.py
@@ -161,6 +161,7 @@ class GetParentImplementation:
     template: ClassVar = 'ql_parent'
 
     classes: List[Class] = field(default_factory=list)
+    additional_imports: List[str] = field(default_factory=list)
 
 
 @dataclass
diff --git a/swift/codegen/templates/ql_class.mustache b/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}} {
diff --git a/swift/codegen/templates/ql_parent.mustache b/swift/codegen/templates/ql_parent.mustache
@@ -1,6 +1,9 @@
 // generated by {{generator}}
 
 import codeql.swift.elements
+{{#additional_imports}}
+import {{.}}
+{{/additional_imports}}
 
 private module Impl {
 {{#classes}}
diff --git a/swift/codegen/test/test_qlgen.py b/swift/codegen/test/test_qlgen.py
@@ -181,19 +181,20 @@ def test_internal_not_in_import_list(generate_import_list):
 
 def test_hierarchy_children(generate_children_implementations):
     assert generate_children_implementations([
-        schema.Class("A", derived={"B", "C"}),
+        schema.Class("A", derived={"B", "C"}, pragmas=["ql_internal"]),
         schema.Class("B", bases=["A"], derived={"D"}),
-        schema.Class("C", bases=["A"], derived={"D"}),
+        schema.Class("C", bases=["A"], derived={"D"}, pragmas=["ql_internal"]),
         schema.Class("D", bases=["B", "C"]),
     ]) == ql.GetParentImplementation(
-        classes=[ql.Class(name="A"),
+        classes=[ql.Class(name="A", ql_internal=True),
                  ql.Class(name="B", bases=["A"], imports=[
                      stub_import_prefix + "A"]),
                  ql.Class(name="C", bases=["A"], imports=[
-                     stub_import_prefix + "A"]),
+                     stub_import_prefix + "A"], ql_internal=True),
                  ql.Class(name="D", final=True, bases=["B", "C"],
                           imports=[stub_import_prefix + cls for cls in "BC"]),
                  ],
+        additional_imports=[stub_import_prefix + cls for cls in "AC"],
     )
 
 
diff --git a/swift/ql/.generated.list b/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
@@ -375,7 +375,7 @@ ql/lib/codeql/swift/generated/ErrorElement.qll 4b032abe8ffb71376a29c63e470a52943
 ql/lib/codeql/swift/generated/File.qll 61454459f5f1ae378bd4970ad1da4f39f3e696bac8a5eebdd162f131995c5316 3e6805f8858cd55dd0e0d0e5aeab923d6a55292dbf98b0029db1ae0208efe684
 ql/lib/codeql/swift/generated/Locatable.qll bdc98b9fb7788f44a4bf7e487ee5bd329473409950a8e9f116d61995615ad849 0b36b4fe45e2aa195e4bb70c50ea95f32f141b8e01e5f23466c6427dd9ab88fb
 ql/lib/codeql/swift/generated/Location.qll 851766e474cdfdfa67da42e0031fc42dd60196ff5edd39d82f08d3e32deb84c1 b29b2c37672f5acff15f1d3c5727d902f193e51122327b31bd27ec5f877bca3b
-ql/lib/codeql/swift/generated/ParentChild.qll cae61c8f54bd23e0d1faf7e33403020dabed5d34e4ccc89c2bcedbb57c336e0b 80e186d0ee76757a0f86cdb77703c66a7e6e5c4f3602f5bbb75912865004ca46
+ql/lib/codeql/swift/generated/ParentChild.qll 0f8559232a046fe48fff4add61caf9563daf2b921bf898d19de70165669681e4 d229113e146673e446b7e4517ee898d524edf16ab9cfcf01aab18d79042242ae
 ql/lib/codeql/swift/generated/PureSynthConstructors.qll 173c0dd59396a1de26fe870e3bc2766c46de689da2a4d8807cb62023bbce1a98 173c0dd59396a1de26fe870e3bc2766c46de689da2a4d8807cb62023bbce1a98
 ql/lib/codeql/swift/generated/Raw.qll 112397ddf13db0b83177c940f6681d2d1cf5224b8931ed8cdaaee63f3e9ce731 fbdd886f151a31709dcb058c790bdb2d8c304ac4183cfd5ddafcd70637bcf5a3
 ql/lib/codeql/swift/generated/Synth.qll 6a9e6edcc43732b6cf947d88b9562a591a54c651aa8e4f94b8b6139ff3f84b63 a1f37bb361fed57104f8277c8f8b1962a0a54b1f80c2d676e71c40a91d3af529
@@ -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
diff --git a/swift/ql/lib/codeql/swift/elements.qll b/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
diff --git a/swift/ql/lib/codeql/swift/generated/Callable.qll b/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() }
 
diff --git a/swift/ql/lib/codeql/swift/generated/ParentChild.qll b/swift/ql/lib/codeql/swift/generated/ParentChild.qll
@@ -1,5 +1,6 @@
 // generated by codegen/codegen.py
 import codeql.swift.elements
+import codeql.swift.elements.expr.SelfApplyExpr
 
 private module Impl {
   private Element getImmediateChildOfElement(Element e, int index, string partialPredicateCall) {
diff --git a/swift/ql/lib/codeql/swift/generated/decl/PoundDiagnosticDecl.qll b/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()
diff --git a/swift/ql/lib/codeql/swift/generated/decl/VarDecl.qll b/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()
diff --git a/swift/ql/lib/codeql/swift/generated/expr/SelfApplyExpr.qll b/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.
diff --git a/swift/schema.py b/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):
