Merge pull request #12842 from github/redsun82/swift-qlgen-qldoc

Swift: add QLdoc for generated `Raw` and `Synth` modules

Author: redsun82

misc/codegen/templates/ql_db.mustache

@@ -1,5 +1,15 @@
+/**
+ * INTERNAL: Do not use.
+ * This module holds thin fully generated class definitions around DB entities.
+ */
 module Raw {
   {{#classes}}
+  /**
+   * INTERNAL: Do not use.
+  {{#doc}}
+   * {{.}}
+  {{/doc}}
+   */
   class {{name}} extends {{db_id}}{{#bases}}, {{.}}{{/bases}} {
     {{#root}}string toString() { none() }{{/root}}
     {{#final}}override string toString() { result = "{{name}}" }{{/final}}

misc/codegen/templates/ql_ipa_types.mustache

@@ -1,22 +1,42 @@
+/**
+ * INTERNAL: Do not use.
+ * This module defines the IPA layer on top of raw DB entities, and the conversions between the two
+ * layers.
+ */
+
 private import {{import_prefix}}.SynthConstructors
 private import {{import_prefix}}.Raw
 
 cached module Synth {
+  /**
+   * INTERNAL: Do not use.
+   * The synthesized type of all elements.
+   */
   cached newtype T{{root}} =
     {{#final_classes}}
     {{^first}}
     or
     {{/first}}
+    /**
+     * INTERNAL: Do not use.
+     */
     T{{name}}({{#params}}{{^first}}, {{/first}}{{type}} {{param}}{{/params}}){{#has_params}} { construct{{name}}({{#params}}{{^first}}, {{/first}}{{param}}{{/params}}) }{{/has_params}}
     {{/final_classes}}
 
   {{#non_final_classes}}
   {{^root}}
+  /**
+   * INTERNAL: Do not use.
+   */
   class T{{name}} = {{#derived}}{{^first}} or {{/first}}T{{name}}{{/derived}};
   {{/root}}
   {{/non_final_classes}}
 
   {{#final_classes}}
+  /**
+   * INTERNAL: Do not use.
+   * Converts a raw element to a synthesized `T{{name}}`, if possible.
+   */
   cached T{{name}} convert{{name}}FromRaw(Raw::Element e) {
     {{^is_fresh_ipa}}
     result = T{{name}}(e)
@@ -28,6 +48,10 @@ cached module Synth {
   {{/final_classes}}
 
   {{#non_final_classes}}
+  /**
+   * INTERNAL: Do not use.
+   * Converts a raw DB element to a synthesized `T{{name}}`, if possible.
+   */
   cached T{{name}} convert{{name}}FromRaw(Raw::Element e) {
     {{#derived}}
     {{^first}}
@@ -39,6 +63,10 @@ cached module Synth {
   {{/non_final_classes}}
 
   {{#final_classes}}
+  /**
+   * INTERNAL: Do not use.
+   * Converts a synthesized `T{{name}}` to a raw DB element, if possible.
+   */
   cached Raw::Element convert{{name}}ToRaw(T{{name}} e) {
     {{^is_fresh_ipa}}
     e = T{{name}}(result)
@@ -50,6 +78,10 @@ cached module Synth {
   {{/final_classes}}
 
   {{#non_final_classes}}
+  /**
+   * INTERNAL: Do not use.
+   * Converts a synthesized `T{{name}}` to a raw DB element, if possible.
+   */
   cached Raw::Element convert{{name}}ToRaw(T{{name}} e) {
     {{#derived}}
     {{^first}}

swift/ql/.generated.list

@@ -386,8 +386,8 @@ ql/lib/codeql/swift/generated/OtherAvailabilitySpec.qll 0e26a203b26ff0581b7396b0
 ql/lib/codeql/swift/generated/ParentChild.qll 3998d73048297cf2df42176b0060c025e57d409d56f3fbfab9c202bd46c07b5e 425b01328baf38bd5e46403e11b25b0e17cd5bc40731dbf64a46e01604611e15
 ql/lib/codeql/swift/generated/PlatformVersionAvailabilitySpec.qll f82d9ca416fe8bd59b5531b65b1c74c9f317b3297a6101544a11339a1cffce38 7f5c6d3309e66c134107afe55bae76dfc9a72cb7cdd6d4c3706b6b34cee09fa0
 ql/lib/codeql/swift/generated/PureSynthConstructors.qll 173c0dd59396a1de26fe870e3bc2766c46de689da2a4d8807cb62023bbce1a98 173c0dd59396a1de26fe870e3bc2766c46de689da2a4d8807cb62023bbce1a98
-ql/lib/codeql/swift/generated/Raw.qll 16ef0c379f1b3ceb73df393a34b8d2c5c4fb180e337fb3b8f33078fa9d827b7e 4b608cd9fc3f425fc568322ae17036e6407a54d0a6a30ff03fe04942f4ef897f
-ql/lib/codeql/swift/generated/Synth.qll 1b60c8eab214c8f9a3a1fb39a8785979bc3d86f2615ba0a580c35e17fd496851 052940a87ffb32214b1b3c774bc643aa5d4f31c484d3121b4da384c2839cb10b
+ql/lib/codeql/swift/generated/Raw.qll cda40b44e2b72ceb32a3c03d2f16028fc4db723c8cdc0a9638693794f4f07411 eb4b59f4dbd2159f59132994e6d1840a1273e5c316232b8439ddc0cc08ef8736
+ql/lib/codeql/swift/generated/Synth.qll e26debaea7feaabbdd4180983a03fa406584e2a0dc4902520d5549d106770fee a448e51acba628d63fc4ae59aa23efa7cd5b567230ae24749d31d2a4ad51baf9
 ql/lib/codeql/swift/generated/SynthConstructors.qll bb0c69cea79a06ec3cc0e176fc6e63cfe125107a45373e41083fc4de056133b8 bb0c69cea79a06ec3cc0e176fc6e63cfe125107a45373e41083fc4de056133b8
 ql/lib/codeql/swift/generated/UnknownFile.qll 0fcf9beb8de79440bcdfff4bb6ab3dd139bd273e6c32754e05e6a632651e85f6 0fcf9beb8de79440bcdfff4bb6ab3dd139bd273e6c32754e05e6a632651e85f6
 ql/lib/codeql/swift/generated/UnknownLocation.qll e50efefa02a0ec1ff635a00951b5924602fc8cab57e5756e4a039382c69d3882 e50efefa02a0ec1ff635a00951b5924602fc8cab57e5756e4a039382c69d3882