Merge pull request github#12137 from github/redsun82/swift-doc-for-schema-doc

Swift: add documentation for generated documentation

Author: redsun82

swift/schema.py

@@ -5,6 +5,8 @@
 * no flow control
 * no aliases
 * only class definitions with annotations and `include` calls
+
+For how documentation of generated QL code works, please read schema_documentation.md.
 """
 
 from swift.codegen.lib.schema.defs import *

swift/schema_documentation.md

@@ -0,0 +1,114 @@
+# Documenting `schema.py` entities
+
+## Classes
+
+Classes can be documented with plain python docstrings, for example
+
+```
+class ErrorElement(Locatable):
+    '''The superclass of all elements indicating some kind of error.'''
+    pass
+```
+
+This gets copied verbatim as QL doc comments for the class (with some internal handling for preservation of indentation,
+as explained in https://peps.python.org/pep-0257/#handling-docstring-indentation).
+
+## Properties
+
+Properties by default get a generated doc comment created from the name of the property and the enclosing class. So for
+example property `name` in class `File` will get documented as
+
+```
+/**
+ * Gets the name of this file.
+ */
+```
+
+This documentation generation will expand common abbreviations. The list of expanded abbreviations can be found
+in [`codegen/generators/qlgen.py`](./codegen/generators/qlgen.py) as a dictionary under the `abbreviations` variable.
+
+The `name of this file` part in the example above can be customized by appending `| doc("<replacement>")` to the
+property specification, for example
+
+```
+class Locatable(Element):
+    location: optional[Location] | doc("location associated with this element in the code")
+```
+
+When keeping the default documentation header, the name used for the class (for example `file` above) can be customized
+at the class level by applying to the class the `@ql.default_doc_name("<replacement>")` decorator, for example
+
+```
+@ql.default_doc_name("function type")
+class AnyFunctionType(Type):
+  ...
+```
+
+Additionally, a description can be given which will be added after the documentation header
+using `| desc("<description>")`. For example
+
+```
+class PoundDiagnosticDecl(Decl):
+    kind: int | desc("This is 1 for `#error` and 2 for `#warning`.")
+```
+
+will result in
+
+```
+/**
+ * Gets the kind of this pound diagnostic declaration.
+ *
+ * This is 1 for `#error` and 2 for `#warning`.
+ */
+```
+
+### Plural/singular
+
+Notice that for repeated properties both the plural and the singular forms will be present in documentation. What term
+is taken to be pluralized/singularized depends on customization:
+
+* for auto-generated documentation headers, the _last_ word of the property name will be taken;
+* for headers overridden with `doc("<override>")`, the _first_ word of the override will be taken.
+
+So for example:
+
+```
+generic_type_params: list[GenericTypeParamDecl]
+   -> generic type parameter/generic type parameters of this generic context
+arguments: list[Argument] | doc("arguments passed to the applied function")
+   -> argument/arguments passed to the applied function
+```
+
+If this behaviour is not wanted, this can be overridden by enclosing the term to be pluralized/singularized in `{ }`
+within `doc`. So for example
+
+```
+class Foo:
+    names_of_the_things: list[string] | doc("{names} of the things in this foo")
+    silly_cats_or_dogs: list[Animal] | doc("silly {cats} or {dogs} in this foo")
+```
+
+## Predicates
+
+Similarly as properties, predicates get by default an automatically generated doc comment from the class name and the
+predicate name. For example
+
+```
+class ImportDecl(Decl):
+    is_exported: predicate
+```
+
+will generate the doc
+
+```
+/**
+ * Holds if this import declaration is exported.
+ */
+```
+
+And similarly to properties, one can:
+
+* customize everything that comes strictly after `if` with `| doc("<replacement>")`;
+* customize the default name for used for the class (`import declaration` in the example above) with
+  the `@ql.default_doc_name("<replacement>")` class decorator;
+* add a more in-depth description with `| desc("<description>")`.