Add a warning for undocumented nodes

TN: S129-007

langkit/compile_context.py

@@ -1144,6 +1144,22 @@ class CompileCtx(object):
         for prop in self.all_properties(include_inherited=False):
             prop._uses_envs = bool(prop._uses_envs)
 
+    def warn_on_undocumented(self, node):
+        """
+        Emit a warning if ``node`` is not documented.
+        """
+        # Ignore nodes that are created during the expansion of EnumNode: users
+        # cannot add documentation for these.
+        if node.base and node.base.is_enum_node:
+            return
+
+        # Likewise for the very abstract generic list type
+        elif node.is_generic_list_type:
+            return
+
+        WarningSet.undocumented_nodes.warn_if(
+            not node._doc, 'This node lacks documentation')
+
     def warn_unused_private_properties(self):
         """
         Check that all private properties are actually used: if one is not,
@@ -1542,6 +1558,8 @@ class CompileCtx(object):
                        CompileCtx.warn_unreachable_base_properties),
             PropertyPass('warn on undocumented public properties',
                          PropertyDef.warn_on_undocumented_public_property),
+            ASTNodePass('warn on undocumented nodes',
+                        CompileCtx.warn_on_undocumented),
             GlobalPass('compute composite types',
                        CompileCtx.compute_composite_types),
             ASTNodePass('expose public structs and arrays types in APIs',

langkit/diagnostics.py

@@ -380,6 +380,10 @@ class WarningSet(object):
         'undocumented-public-properties', True,
         'Warn if a public property is left undocumented.'
     )
+    undocumented_nodes = WarningDescriptor(
+        'undocumented-nodes', True,
+        'Warn if a node is left undocumented.'
+    )
     imprecise_field_type_annotations = WarningDescriptor(
         'imprecise-field-type-annotations', True,
         'Warn about parsing field type annotations that are not as precise as'
@@ -387,7 +391,7 @@ class WarningSet(object):
     )
     available_warnings = [
         prop_only_entities, unused_bindings, unparser_bad_grammar,
-        unused_node_type, undocumented_public_properties,
+        unused_node_type, undocumented_public_properties, undocumented_nodes,
         imprecise_field_type_annotations,
     ]
 

scripts/create-project.py

@@ -90,6 +90,9 @@ class {lang_name}Node(ASTNode):
     pass
 
 class ExampleNode({lang_name}Node):
+    """
+    Example node.
+    """
     pass
 
 {lang_name_slug}_grammar = Grammar('main_rule')

testsuite/python_support/utils.py

@@ -16,8 +16,9 @@ from testsuite_support.valgrind import valgrind_cmd
 
 default_warning_set = WarningSet()
 
-# We don't want to be forced to provide dummy docs for public properties in
-# testcases.
+# We don't want to be forced to provide dummy docs for nodes and public
+# properties in testcases.
+default_warning_set.disable(WarningSet.undocumented_nodes)
 default_warning_set.disable(WarningSet.undocumented_public_properties)
 
 pretty_print = bool(int(os.environ.get('LANGKIT_PRETTY_PRINT', '0')))

testsuite/tests/properties/warn_public_doc/test.out

@@ -1,6 +1,6 @@
-File "test.py", line 24, in FooNode.undoc_prop
+File "test.py", line 27, in FooNode.undoc_prop
     Warning: This property is public but it lacks documentation
-File "test.py", line 30, in FooNode.will_doc_prop
+File "test.py", line 33, in FooNode.will_doc_prop
     Warning: This property is public but it lacks documentation
 Code generation was successful
 Done

testsuite/tests/properties/warn_public_doc/test.py

@@ -9,6 +9,9 @@ from utils import emit_and_print_errors
 
 
 class FooNode(ASTNode):
+    """
+    Root node.
+    """
 
     # This property is documented, so it should not have a warning
     @langkit_property(public=True, return_type=T.Bool,
@@ -33,6 +36,9 @@ class FooNode(ASTNode):
 
 
 class Example(FooNode):
+    """
+    Example node.
+    """
 
     # This property is undocumented but it inherits a documented one, so it
     # should not have a warning.