Merge pull request github#14715 from github/redsun82/gen-file-docs

Swift: add more doc strings to generated things

Author: redsun82

misc/codegen/generators/qlgen.py

@@ -102,7 +102,8 @@ def _get_doc(cls: schema.Class, prop: schema.Property, plural=None):
     return f"{prop_name} of this {class_name}"
 
 
-def get_ql_property(cls: schema.Class, prop: schema.Property, lookup: typing.Dict[str, schema.Class], prev_child: str = "") -> ql.Property:
+def get_ql_property(cls: schema.Class, prop: schema.Property, lookup: typing.Dict[str, schema.Class],
+                    prev_child: str = "") -> ql.Property:
     args = dict(
         type=prop.type if not prop.is_predicate else "predicate",
         qltest_skip="qltest_skip" in prop.pragmas,
@@ -310,7 +311,8 @@ def _get_stub(cls: schema.Class, base_import: str, generated_import_prefix: str)
             ]
     else:
         accessors = []
-    return ql.Stub(name=cls.name, base_import=base_import, import_prefix=generated_import_prefix, synth_accessors=accessors)
+    return ql.Stub(name=cls.name, base_import=base_import, import_prefix=generated_import_prefix,
+                   synth_accessors=accessors, ql_internal="ql_internal" in cls.pragmas)
 
 
 def generate(opts, renderer):
@@ -426,7 +428,7 @@ def generate(opts, renderer):
         for stub_file, data in stubs.items():
             renderer.render(data, stub_file)
         renderer.render(ql.Synth.Types(root.name, generated_import_prefix,
-                        final_synth_types, non_final_synth_types), out / "Synth.qll")
+                                       final_synth_types, non_final_synth_types), out / "Synth.qll")
         renderer.render(ql.ImportList(constructor_imports), out / "SynthConstructors.qll")
         renderer.render(ql.ImportList(synth_constructor_imports), out / "PureSynthConstructors.qll")
         if opts.ql_format:

misc/codegen/lib/ql.py

@@ -166,6 +166,7 @@ class Stub:
     base_import: str
     import_prefix: str
     synth_accessors: List[SynthUnderlyingAccessor] = field(default_factory=list)
+    ql_internal: bool = False
 
     @property
     def has_synth_accessors(self) -> bool:

misc/codegen/templates/ql_class.mustache

@@ -1,21 +1,23 @@
 // generated by {{generator}}
+/**
+ * This module provides the generated definition of `{{name}}`.
+ * INTERNAL: Do not import directly.
+ */
+
 private import {{import_prefix}}.Synth
 private import {{import_prefix}}.Raw
 {{#imports}}
 import {{.}}
 {{/imports}}
 
 module Generated {
-  {{#has_doc}}
   /**
-  {{#ql_internal}}
-   * INTERNAL: Do not use.
-  {{/ql_internal}}
   {{#doc}}
    * {{.}}
   {{/doc}}
+   * INTERNAL: Do not reference the `Generated::{{name}}` class directly.
+   * Use the subclass `{{name}}`, where the following predicates are available.
    */
-  {{/has_doc}}
   class {{name}} extends Synth::T{{name}}{{#bases}}, {{.}}{{/bases}} {
   {{#root}}
     /**

misc/codegen/templates/ql_imports.mustache

@@ -1,4 +1,8 @@
 // generated by {{generator}}
+/**
+ * This module exports all modules providing `Element` subclasses.
+ */
+
 {{#imports}}
 import {{.}}
 {{/imports}}

misc/codegen/templates/ql_parent.mustache

@@ -1,4 +1,7 @@
 // generated by {{generator}}
+/**
+ * This module provides the generated parent/child relationship.
+ */
 
 {{#imports}}
 import {{.}}

misc/codegen/templates/ql_stub.mustache

@@ -1,4 +1,10 @@
 // generated by {{generator}}, remove this comment if you wish to edit this file
+/**
+ * This module provides a hand-modifiable wrapper around the generated class `{{name}}`.
+{{#ql_internal}}
+ * INTERNAL: Do not use.
+{{/ql_internal}}
+ */
 private import {{base_import}}
 {{#has_synth_accessors}}
 private import {{import_prefix}}.Raw

misc/codegen/templates/ql_synth_constructor_stub.mustache

@@ -1,4 +1,9 @@
 // generated by {{generator}}, remove this comment if you wish to edit this file
+/**
+ *  This module defines the hook used internally to tweak the characteristic predicate of
+ *  `{{cls.name}}` synthesized instances.
+ *  INTERNAL: Do not use.
+ */
 private import {{import_prefix}}.Raw
 {{#cls}}
 {{#is_db}}
@@ -7,6 +12,10 @@ private import {{import_prefix}}.PureSynthConstructors
 {{/has_subtracted_synth_types}}
 {{/is_db}}
 
+/**
+ *  The characteristic predicate of `{{name}}` synthesized instances.
+ *  INTERNAL: Do not use.
+ */
 predicate construct{{name}}({{#params}}{{^first}}, {{/first}}{{type}} {{param}}{{/params}}) {
   {{#is_db}}
   {{#subtracted_synth_types}}{{^first}} and {{/first}}not construct{{name}}(id){{/subtracted_synth_types}}

misc/codegen/test/test_qlgen.py

@@ -153,6 +153,15 @@ def test_one_empty_class(generate_classes):
     }
 
 
+def test_one_empty_internal_class(generate_classes):
+    assert generate_classes([
+        schema.Class("A", pragmas=["ql_internal"])
+    ]) == {
+        "A.qll": (a_ql_stub(name="A", ql_internal=True),
+                  a_ql_class(name="A", final=True, ql_internal=True)),
+    }
+
+
 def test_hierarchy(generate_classes):
     assert generate_classes([
         schema.Class("D", bases=["B", "C"]),