Swift: generate class docs

Python docstrings in `schema.py` are now added to the generated classes.

As an example, a docstring is added to `Expr`.

Author: redsun82

swift/codegen/generators/qlgen.py

@@ -109,6 +109,7 @@ def get_ql_class(cls: schema.Class, lookup: typing.Dict[str, schema.Class]):
         properties=properties,
         dir=pathlib.Path(cls.group or ""),
         ipa=bool(cls.ipa),
+        doc=cls.doc,
         **pragmas,
     )
 

swift/codegen/lib/ql.py

@@ -70,6 +70,10 @@ def is_single(self):
     def is_child(self):
         return self.prev_child is not None
 
+    @property
+    def has_doc(self) -> bool:
+        return bool(self.doc)
+
 
 @dataclass
 class Base:
@@ -94,6 +98,7 @@ class Class:
     qltest_collapse_hierarchy: bool = False
     qltest_uncollapse_hierarchy: bool = False
     ipa: bool = False
+    doc: List[str] = field(default_factory=list)
 
     def __post_init__(self):
         self.bases = [Base(str(b), str(prev)) for b, prev in zip(self.bases, itertools.chain([""], self.bases))]
@@ -120,6 +125,10 @@ def has_children(self) -> bool:
     def last_base(self) -> str:
         return self.bases[-1].base if self.bases else ""
 
+    @property
+    def has_doc(self) -> bool:
+        return bool(self.doc)
+
 
 @dataclass
 class Stub:

swift/codegen/templates/ql_class.mustache

@@ -6,6 +6,13 @@ import {{.}}
 {{/imports}}
 
 module Generated {
+  {{#has_doc}}
+  /**
+  {{#doc}}
+   * {{.}}
+  {{/doc}}
+   */
+  {{/has_doc}}
   class {{name}} extends Synth::T{{name}}{{#bases}}, {{.}}{{/bases}} {
     {{#root}}
     string toString() { none() } // overridden by subclasses

swift/codegen/test/test_ql.py

@@ -127,5 +127,25 @@ def test_class_with_children():
     assert cls.has_children is True
 
 
+def test_class_with_doc():
+    cls = ql.Class("Class", doc=["foo", "bar"])
+    assert cls.has_doc is True
+
+
+def test_class_without_doc():
+    cls = ql.Class("Class", doc=[])
+    assert cls.has_doc is False
+
+
+def test_property_with_doc():
+    prop = ql.Property("X", "int", doc=["foo", "bar"])
+    assert prop.has_doc is True
+
+
+def test_class_without_doc():
+    prop = ql.Property("X", "int")
+    assert prop.has_doc is False
+
+
 if __name__ == '__main__':
     sys.exit(pytest.main([__file__] + sys.argv[1:]))

swift/codegen/test/test_qlgen.py

@@ -350,6 +350,16 @@ def test_single_class_property(generate_classes, is_child, prev_child):
     }
 
 
+def test_class_with_doc(generate_classes):
+    doc = ["Very important class.", "Very."]
+    assert generate_classes([
+        schema.Class("A", doc=doc),
+    ]) == {
+        "A.qll": (ql.Stub(name="A", base_import=gen_import_prefix + "A"),
+                  ql.Class(name="A", final=True, doc=doc)),
+    }
+
+
 def test_class_dir(generate_classes):
     dir = "another/rel/path"
     assert generate_classes([

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

@@ -5,6 +5,9 @@ import codeql.swift.elements.AstNode
 import codeql.swift.elements.type.Type
 
 module Generated {
+  /**
+   * The base class for all expressions in Swift.
+   */
   class Expr extends Synth::TExpr, AstNode {
     Type getImmediateType() {
       result = Synth::convertTypeFromRaw(Synth::convertExprToRaw(this).(Raw::Expr).getType())

swift/schema.py

@@ -68,6 +68,7 @@ class Decl(AstNode):
 
 @group("expr")
 class Expr(AstNode):
+    """The base class for all expressions in Swift."""
     type: optional[Type]
 
 @group("pattern")