Swift: docname and desc examples

Author: redsun82

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

@@ -65,6 +65,8 @@ module Generated {
 
     /**
      * Gets the body, if it exists.
+     *
+     * The body is absent within protocol declarations.
      */
     final BraceStmt getBody() { result = getImmediateBody().resolve() }
 

swift/ql/lib/codeql/swift/generated/type/GenericFunctionType.qll

@@ -5,11 +5,14 @@ import codeql.swift.elements.type.AnyFunctionType
 import codeql.swift.elements.type.GenericTypeParamType
 
 module Generated {
+  /**
+   * The type of a generic function with type parameters
+   */
   class GenericFunctionType extends Synth::TGenericFunctionType, AnyFunctionType {
     override string getAPrimaryQlClass() { result = "GenericFunctionType" }
 
     /**
-     * Gets the `index`th generic param.
+     * Gets the `index`th generic parameter.
      * This is taken from the "hidden" AST and should only be used to be overridden by classes.
      */
     GenericTypeParamType getImmediateGenericParam(int index) {
@@ -20,19 +23,19 @@ module Generated {
     }
 
     /**
-     * Gets the `index`th generic param.
+     * Gets the `index`th generic parameter.
      */
     final GenericTypeParamType getGenericParam(int index) {
       result = getImmediateGenericParam(index).resolve()
     }
 
     /**
-     * Gets any of the generic params.
+     * Gets any of the generic parameters.
      */
     final GenericTypeParamType getAGenericParam() { result = getGenericParam(_) }
 
     /**
-     * Gets the number of generic params.
+     * Gets the number of generic parameters.
      */
     final int getNumberOfGenericParams() { result = count(getAGenericParam()) }
   }

swift/schema.py

@@ -139,7 +139,7 @@ class ParamDecl(VarDecl):
 class Callable(Element):
     self_param: optional[ParamDecl] | child
     params: list[ParamDecl] | child
-    body: optional["BraceStmt"] | child
+    body: optional["BraceStmt"] | child | desc("The body is absent within protocol declarations.")
 
 class AbstractFunctionDecl(GenericContext, ValueDecl, Callable):
     name: string
@@ -903,7 +903,8 @@ class FunctionType(AnyFunctionType):
     pass
 
 class GenericFunctionType(AnyFunctionType):
-    generic_params: list["GenericTypeParamType"]
+    """ The type of a generic function with type parameters """
+    generic_params: list["GenericTypeParamType"] | docname("generic parameters")
 
 class GenericTypeParamType(SubstitutableType):
     pass