Swift: allow default class doc name to be set for properties

Author: redsun82

swift/codegen/generators/qlgen.py

@@ -95,7 +95,7 @@ def _get_doc(cls: schema.Class, prop: schema.Property, plural=None):
         return format.format(**{noun: transform(noun) for noun in nouns})
 
     prop_name = _humanize(prop.name)
-    class_name = _humanize(inflection.underscore(cls.name))
+    class_name = cls.default_doc_name or _humanize(inflection.underscore(cls.name))
     if prop.is_predicate:
         return f"this {class_name} {prop_name}"
     if plural is not None:

swift/codegen/lib/schema/defs.py

@@ -33,14 +33,13 @@ def include(source: str):
         "__includes", []).append(source)
 
 
+@_dataclass
 class _Pragma(_schema.PropertyModifier):
     """ A class or property pragma.
     For properties, it functions similarly to a `_PropertyModifier` with `|`, adding the pragma.
     For schema classes it acts as a python decorator with `@`.
     """
-
-    def __init__(self, pragma):
-        self.pragma = pragma
+    pragma: str
 
     def modify(self, prop: _schema.Property):
         prop.pragmas.append(self.pragma)
@@ -54,6 +53,15 @@ def __call__(self, cls: type) -> type:
         return cls
 
 
+@_dataclass
+class _DefaultDocNameClassModifier:
+    doc_name: str
+
+    def __call__(self, cls: type) -> type:
+        cls._doc_name = self.doc_name
+        return cls
+
+
 class _Optionalizer(_schema.PropertyModifier):
     def modify(self, prop: _schema.Property):
         K = _schema.Property.Kind
@@ -122,6 +130,10 @@ def f(cls: type) -> type:
     uncollapse_hierarchy=_Pragma("qltest_uncollapse_hierarchy"),
 )
 
+ql = _Namespace(
+    default_doc_name=_DefaultDocNameClassModifier,
+)
+
 cpp = _Namespace(
     skip=_Pragma("cpp_skip"),
 )

swift/codegen/lib/schema/schema.py

@@ -80,6 +80,7 @@ class Class:
     pragmas: List[str] = field(default_factory=list)
     ipa: Optional[IpaInfo] = None
     doc: List[str] = field(default_factory=list)
+    default_doc_name: Optional[str] = None
 
     @property
     def final(self):
@@ -207,6 +208,7 @@ def _get_class(cls: type) -> Class:
                      for n, a in cls.__dict__.get("__annotations__", {}).items()
                  ],
                  doc=split_doc(cls.__doc__),
+                 default_doc_name=cls.__dict__.get("_doc_name"),
                  )
 
 

swift/codegen/test/test_qlgen.py

@@ -774,5 +774,20 @@ def test_property_doc_override_with_format(generate_classes):
     }
 
 
+def test_property_on_class_with_default_doc_name(generate_classes):
+    assert generate_classes([
+        schema.Class("MyObject", properties=[
+            schema.SingleProperty("foo", "bar")],
+            default_doc_name="baz"),
+    ]) == {
+        "MyObject.qll": (ql.Stub(name="MyObject", base_import=gen_import_prefix + "MyObject"),
+                         ql.Class(name="MyObject", final=True,
+                                  properties=[
+                                      ql.Property(singular="Foo", type="bar", tablename="my_objects",
+                                                  tableparams=["this", "result"], doc="foo of this baz"),
+                                  ])),
+    }
+
+
 if __name__ == '__main__':
     sys.exit(pytest.main([__file__] + sys.argv[1:]))

swift/codegen/test/test_schema.py

@@ -554,5 +554,17 @@ class A:
     }
 
 
+def test_class_default_doc_name():
+    @schema.load
+    class data:
+        @defs.ql.default_doc_name("b")
+        class A:
+            pass
+
+    assert data.classes == {
+        'A': schema.Class('A', default_doc_name="b"),
+    }
+
+
 if __name__ == '__main__':
     sys.exit(pytest.main([__file__] + sys.argv[1:]))

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

@@ -6,7 +6,7 @@ import codeql.swift.elements.type.Type
 module Generated {
   class AnyFunctionType extends Synth::TAnyFunctionType, Type {
     /**
-     * Gets the result of this any function type.
+     * Gets the result of this function type.
      *
      * This includes nodes from the "hidden" AST. It can be overridden in subclasses to change the
      * behaviour of both the `Immediate` and non-`Immediate` versions.
@@ -19,12 +19,12 @@ module Generated {
     }
 
     /**
-     * Gets the result of this any function type.
+     * Gets the result of this function type.
      */
     final Type getResult() { result = getImmediateResult().resolve() }
 
     /**
-     * Gets the `index`th parameter type of this any function type (0-based).
+     * Gets the `index`th parameter type of this function type (0-based).
      *
      * This includes nodes from the "hidden" AST. It can be overridden in subclasses to change the
      * behaviour of both the `Immediate` and non-`Immediate` versions.
@@ -37,46 +37,46 @@ module Generated {
     }
 
     /**
-     * Gets the `index`th parameter type of this any function type (0-based).
+     * Gets the `index`th parameter type of this function type (0-based).
      */
     final Type getParamType(int index) { result = getImmediateParamType(index).resolve() }
 
     /**
-     * Gets any of the parameter types of this any function type.
+     * Gets any of the parameter types of this function type.
      */
     final Type getAParamType() { result = getParamType(_) }
 
     /**
-     * Gets the number of parameter types of this any function type.
+     * Gets the number of parameter types of this function type.
      */
     final int getNumberOfParamTypes() { result = count(getAParamType()) }
 
     /**
-     * Gets the `index`th parameter label of this any function type (0-based).
+     * Gets the `index`th parameter label of this function type (0-based).
      */
     string getParamLabel(int index) {
       result = Synth::convertAnyFunctionTypeToRaw(this).(Raw::AnyFunctionType).getParamLabel(index)
     }
 
     /**
-     * Gets any of the parameter labels of this any function type.
+     * Gets any of the parameter labels of this function type.
      */
     final string getAParamLabel() { result = getParamLabel(_) }
 
     /**
-     * Gets the number of parameter labels of this any function type.
+     * Gets the number of parameter labels of this function type.
      */
     final int getNumberOfParamLabels() { result = count(getAParamLabel()) }
 
     /**
-     * Holds if this any function type is throwing.
+     * Holds if this type refers to a throwing function.
      */
     predicate isThrowing() {
       Synth::convertAnyFunctionTypeToRaw(this).(Raw::AnyFunctionType).isThrowing()
     }
 
     /**
-     * Holds if this any function type is async.
+     * Holds if this type refers to an `async` function.
      */
     predicate isAsync() {
       Synth::convertAnyFunctionTypeToRaw(this).(Raw::AnyFunctionType).isAsync()

swift/schema.py

@@ -783,12 +783,13 @@ class WhileStmt(LabeledConditionalStmt):
 class TypeRepr(AstNode):
     type: Type
 
+@ql.default_doc_name("function type")
 class AnyFunctionType(Type):
     result: Type
     param_types: list[Type]
     param_labels: list[string]
-    is_throwing: predicate
-    is_async: predicate
+    is_throwing: predicate | doc("this type refers to a throwing function")
+    is_async: predicate | doc("this type refers to an `async` function")
 
 class AnyGenericType(Type):
     parent: optional[Type]