astdoc: add documentation for structure types

TN: Q213-023
AdaCore · Feb 13, 2017 · 91cf97e · 91cf97e
1 parent 3cdf9d2
commit 91cf97e
Showing 1 changed file with 82 additions and 63 deletions.
diff --git a/langkit/astdoc.py b/langkit/astdoc.py
@@ -21,6 +21,80 @@ def format_doc(entity):
     return doc
 
 
+def print_struct(context, file, struct):
+    is_astnode = struct.is_ast_node()
+    base = struct.base() if is_astnode else None
+    fields = list(struct.get_abstract_fields())
+
+    # Do not document internal fields unless everything is public
+    if not context.library_fields_all_public:
+        fields = [f for f in fields if not f.is_internal]
+
+    descr = []
+    if is_astnode:
+        kind = 'node'
+        if struct.abstract:
+            descr.append('<span class="kw">abstract</span>')
+        descr.append('<span class="kw">root</span>'
+                     if base == compiled_types.ASTNode else
+                     astnode_ref(base))
+    else:
+        kind = 'struct'
+    print >> file, (
+        '<dt id="{name}">'
+        '<span class="kw">{kind}</span>'
+        ' <span class="def">{name}</span>'
+        '{descr}</dt>'.format(
+            name=struct.name().camel,
+            kind=kind,
+            descr=' : {}'.format(' '.join(descr)) if descr else ''
+        )
+    )
+    print >> file, '<dd>{}'.format(format_doc(struct))
+
+    print >> file, '<dl>'
+    for f in fields:
+        print_field(context, file, struct, f)
+
+    print >> file, '</dl>'
+    print >> file, '</dd>'
+
+
+def print_field(context, file, struct, field):
+    prefixes = []
+    if field.is_private:
+        prefixes.append('<span class="priv">private</span>')
+    prefixes.append('<span class="kw">{}</span>'.format(
+        'field'
+        if isinstance(field, compiled_types.Field) else
+        'property'
+    ))
+
+    inherit_note = (
+        '' if field.struct == struct else
+        ' [inherited from {}]'.format(field_ref(field))
+    )
+
+    print >> file, (
+        '<dt>{prefixes}'
+        ' <span class="def" id="{node}-{field}">{field}</span>'
+        ' : {type}{inherit_note}</dt>'.format(
+            prefixes=' '.join(prefixes),
+            node=struct.name().camel,
+            field=field.name.lower,
+            type=(
+                astnode_ref(field.type)
+                if field.type in context.astnode_types else
+                field.type.name().camel
+            ),
+            inherit_note=inherit_note
+        )
+    )
+    # Don't repeat the documentation for inheritted fields
+    if field.struct == struct:
+        print >> file, '<dd>{}</dd>'.format(format_doc(field))
+
+
 def astnode_ref(node):
     return '<a href="#{name}" class="ref-link">{name}</a>'.format(
         name=node.name().camel
@@ -75,73 +149,18 @@ def write_astdoc(context, file):
             )
             print >> file, ''
 
-    print >> file, '<h2>AST node types</h2>'
-
-    print >> file, '<dl>'
-    for typ in context.astnode_types:
-        base = typ.base()
-        abs_fields = list(typ.get_abstract_fields())
-
-        # Do not document internal fields unless everything is public
-        if not context.library_fields_all_public:
-            abs_fields = [f for f in abs_fields if not f.is_internal]
-
-        descr = []
-        if typ.abstract:
-            descr.append('<span class="kw">abstract</span>')
-        descr.append('<span class="kw">root</span>'
-                     if base == compiled_types.ASTNode else
-                     astnode_ref(base))
-        print >> file, (
-            '<dt id="{name}">'
-            '<span class="kw">node</span>'
-            ' <span class="def">{name}</span>'
-            ' : {descr}</dt>'.format(
-                name=typ.name().camel,
-                descr=' '.join(descr)
-            )
-        )
-        print >> file, '<dd>{}'.format(format_doc(typ))
+    if context.struct_types:
+        print >> file, '<h2>Structure types</h2>'
 
         print >> file, '<dl>'
-        for abs_field in abs_fields:
-            prefixes = []
-            if abs_field.is_private:
-                prefixes.append('<span class="priv">private</span>')
-            prefixes.append('<span class="kw">{}</span>'.format(
-                'field'
-                if isinstance(abs_field, compiled_types.Field) else
-                'property'
-            ))
-
-            inherit_note = (
-                '' if abs_field.struct == typ else
-                ' [inherited from {}]'.format(field_ref(abs_field))
-            )
-
-            print >> file, (
-                '<dt>{prefixes}'
-                ' <span class="def" id="{node}-{field}">{field}</span>'
-                ' : {type}{inherit_note}</dt>'.format(
-                    prefixes=' '.join(prefixes),
-                    node=typ.name().camel,
-                    field=abs_field.name.lower,
-                    type=(
-                        astnode_ref(abs_field.type)
-                        if abs_field.type in context.astnode_types else
-                        abs_field.type.name().camel
-                    ),
-                    inherit_note=inherit_note
-                )
-            )
-            # Don't repeat the documentation for inheritted fields
-            if abs_field.struct == typ:
-                print >> file, '<dd>{}</dd>'.format(format_doc(abs_field))
-
+        for struct_type in context.struct_types:
+            print_struct(context, file, struct_type)
         print >> file, '</dl>'
 
-        print >> file, '</dd>'
+    print >> file, '<h2>AST node types</h2>'
 
+    print >> file, '<dl>'
+    for typ in context.astnode_types:
+        print_struct(context, file, typ)
     print >> file, '</dl>'
-
     print >> file, '</body></html>'