From ffd078a4e5315f02aaac49ee8d744904d5bce0d7 Mon Sep 17 00:00:00 2001
From: Pierre-Marie de Rodat <derodat@adacore.com>
Date: Tue, 29 Jan 2019 15:13:15 +0100
Subject: [PATCH] Add a warning for undocumented nodes

TN: S129-007
---
 langkit/compile_context.py                     | 18 ++++++++++++++++++
 langkit/diagnostics.py                         |  6 +++++-
 scripts/create-project.py                      |  3 +++
 testsuite/python_support/utils.py              |  5 +++--
 .../tests/properties/warn_public_doc/test.out  |  4 ++--
 .../tests/properties/warn_public_doc/test.py   |  6 ++++++
 6 files changed, 37 insertions(+), 5 deletions(-)

diff --git a/langkit/compile_context.py b/langkit/compile_context.py
index 005aa5f92..24fad16d9 100644
--- a/langkit/compile_context.py
+++ b/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',
diff --git a/langkit/diagnostics.py b/langkit/diagnostics.py
index f7a3029a7..ee869a704 100644
--- a/langkit/diagnostics.py
+++ b/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,
     ]
 
diff --git a/scripts/create-project.py b/scripts/create-project.py
index 16c4bb2cc..b89902efe 100755
--- a/scripts/create-project.py
+++ b/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')
diff --git a/testsuite/python_support/utils.py b/testsuite/python_support/utils.py
index c43832531..4148898b3 100644
--- a/testsuite/python_support/utils.py
+++ b/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')))
diff --git a/testsuite/tests/properties/warn_public_doc/test.out b/testsuite/tests/properties/warn_public_doc/test.out
index 36f99f443..8f83adef9 100644
--- a/testsuite/tests/properties/warn_public_doc/test.out
+++ b/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
diff --git a/testsuite/tests/properties/warn_public_doc/test.py b/testsuite/tests/properties/warn_public_doc/test.py
index 2677453fe..756f1c658 100644
--- a/testsuite/tests/properties/warn_public_doc/test.py
+++ b/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.