Handle doxygen comments for elements separated with a newline

virtuald · virtuald · commit 4260f06fec8e · 2019-12-24T01:41:27.000-05:00
diff --git a/CppHeaderParser/CppHeaderParser.py b/CppHeaderParser/CppHeaderParser.py
@@ -2127,7 +2127,7 @@ def _evaluate_method_stack(self):
                     info["name"],
                     info,
                     self.curTemplate,
-                    self.lex.get_doxygen(),
+                    self._get_stmt_doxygen(),
                     self._get_location(self.nameStack),
                 )
                 klass = self.classes[info["class"]]
@@ -2144,7 +2144,7 @@ def _evaluate_method_stack(self):
                     self.curClass,
                     info,
                     self.curTemplate,
-                    self.lex.get_doxygen(),
+                    self._get_stmt_doxygen(),
                     self._get_location(self.nameStack),
                 )
                 klass = self.classes[self.curClass]
@@ -2161,7 +2161,7 @@ def _evaluate_method_stack(self):
                     None,
                     info,
                     self.curTemplate,
-                    self.lex.get_doxygen(),
+                    self._get_stmt_doxygen(),
                     self._get_location(self.nameStack),
                 )
                 self.functions.append(newMethod)
@@ -2288,7 +2288,7 @@ def _evaluate_property_stack(self, clearStack=True, addToVar=None):
 
             newVar = CppVariable(
                 self.nameStack,
-                self.lex.get_doxygen(),
+                self._get_stmt_doxygen(),
                 self._get_location(self.nameStack),
             )
             newVar["namespace"] = self.current_namespace()
@@ -2305,7 +2305,7 @@ def _evaluate_property_stack(self, clearStack=True, addToVar=None):
             debug_print("Found Global variable")
             newVar = CppVariable(
                 self.nameStack,
-                self.lex.get_doxygen(),
+                self._get_stmt_doxygen(),
                 self._get_location(self.nameStack),
             )
             if addToVar:
@@ -2345,7 +2345,7 @@ def _evaluate_class_stack(self):
         if self.nameStack[0] == "union":
             newClass = CppUnion(
                 self.nameStack,
-                self.lex.get_doxygen(),
+                self._get_stmt_doxygen(),
                 self._get_location(self.nameStack),
             )
             if newClass["name"] == "union ":
@@ -2357,7 +2357,7 @@ def _evaluate_class_stack(self):
             newClass = CppClass(
                 self.nameStack,
                 self.curTemplate,
-                self.lex.get_doxygen(),
+                self._get_stmt_doxygen(),
                 self._get_location(self.nameStack),
             )
             trace_print("NEW CLASS", newClass["name"])
@@ -2631,6 +2631,7 @@ def __init__(self, headerFileName, argType="file", encoding=None, **kwargs):
         # it's slowly getting there!), so take this with a grain of salt.
         #
 
+        self._doxygen_cache = None
         tok = None
         try:
             while True:
@@ -2648,6 +2649,7 @@ def __init__(self, headerFileName, argType="file", encoding=None, **kwargs):
                     if tok.value in self.IGNORE_NAMES:
                         continue
                     elif tok.value == "template":
+                        self._doxygen_cache = self.lex.get_doxygen()
                         self._parse_template()
                         continue
                     elif tok.value == "alignas":
@@ -2666,6 +2668,7 @@ def __init__(self, headerFileName, argType="file", encoding=None, **kwargs):
                     continue
 
                 self.stack.append(tok.value)
+                nslen = len(self.nameStack)
 
                 if tok.type in ("PRECOMP_MACRO", "PRECOMP_MACRO_CONT"):
                     debug_print("PRECOMP: %s", tok)
@@ -2748,6 +2751,7 @@ def __init__(self, headerFileName, argType="file", encoding=None, **kwargs):
 
                 elif tok.type in _namestack_append_tokens:
                     self.nameStack.append(tok.value)
+                    nameStackAppended = True
                 elif tok.type in _namestack_pass_tokens:
                     pass
                 elif tok.type in _namestack_str_tokens:
@@ -2797,6 +2801,11 @@ def __init__(self, headerFileName, argType="file", encoding=None, **kwargs):
                     self.stack = []
                     self.nameStack = []
 
+                newNsLen = len(self.nameStack)
+                if nslen != newNsLen and newNsLen == 1:
+                    if not self.curTemplate:
+                        self._doxygen_cache = self.lex.get_doxygen()
+
         except Exception as e:
             if debug:
                 raise
@@ -2829,6 +2838,7 @@ def __init__(self, headerFileName, argType="file", encoding=None, **kwargs):
         # Delete some temporary variables
         for key in [
             "_precomp_macro_buf",
+            "_doxygen_cache",
             "lex",
             "nameStack",
             "nameSpaces",
@@ -2856,6 +2866,14 @@ def _get_location(self, stack):
 
         return self.lex.current_location()
 
+    def _get_stmt_doxygen(self):
+        # retrieves the doxygen comment associated with an accumulated
+        # statement (since doxygen comments have to be retrieved immediately)
+        doxygen, self._doxygen_cache = self._doxygen_cache, ""
+        if not doxygen:
+            doxygen = self.lex.get_doxygen()
+        return doxygen
+
     def _parse_error(self, tokens, expected):
         if not tokens:
             # common case after a failed token_if
@@ -3003,13 +3021,13 @@ def _evaluate_stack(self, token=None):
                     alias = self.nameStack[1]
                     ns, stack = _split_namespace(self.nameStack[3:])
                     atype = CppVariable(
-                        stack, self.lex.get_doxygen(), self._get_location(stack)
+                        stack, self._get_stmt_doxygen(), self._get_location(stack)
                     )
                 else:
                     # using foo::bar
                     ns, stack = _split_namespace(self.nameStack[1:])
                     atype = CppVariable(
-                        stack, self.lex.get_doxygen(), self._get_location(stack)
+                        stack, self._get_stmt_doxygen(), self._get_location(stack)
                     )
                     alias = atype["type"]
 
@@ -3158,7 +3176,7 @@ def _parse_enum(self):
         """
 
         # entry: enum token was just consumed
-        doxygen = self.lex.get_doxygen()
+        doxygen = self._get_stmt_doxygen()
         location = self.lex.current_location()
 
         nametok = self.lex.token()
diff --git a/CppHeaderParser/lexer.py b/CppHeaderParser/lexer.py
@@ -147,8 +147,8 @@ def get_doxygen(self):
             comments don't exist.
         """
 
-        # assuption: only time you call this function is after a name
-        # token is consumed along with all its pieces
+        # Assumption: This function is either called at the beginning of a
+        # statement or at the end of a statement
 
         if self.comments:
             comments = self.comments
diff --git a/CppHeaderParser/test/test_CppHeaderParser.py b/CppHeaderParser/test/test_CppHeaderParser.py
@@ -3239,5 +3239,60 @@ def test_fn(self):
         self.assertEqual("copy", fn["name"])
 
 
+class MessedUpDoxygen_TestCase(unittest.TestCase):
+    def setUp(self):
+        self.cppHeader = CppHeaderParser.CppHeader(
+            """
+
+/// fn comment
+void
+fn();
+
+/// var comment
+int
+v1 = 0;
+
+int
+v2 = 0; /// var2 comment
+
+/// cls comment
+class
+C {};
+
+/// template comment
+template <typename T>
+class
+C2 {};
+
+""",
+            "string",
+        )
+
+    def test_fn(self):
+        fn = self.cppHeader.functions[0]
+        self.assertEqual("fn", fn["name"])
+        self.assertEqual("/// fn comment", fn["doxygen"])
+
+    def test_var1(self):
+        v = self.cppHeader.variables[0]
+        self.assertEqual("v1", v["name"])
+        self.assertEqual("/// var comment", v["doxygen"])
+
+    def test_var2(self):
+        v = self.cppHeader.variables[1]
+        self.assertEqual("v2", v["name"])
+        self.assertEqual("/// var2 comment", v["doxygen"])
+
+    def test_cls(self):
+        c = self.cppHeader.classes["C"]
+        self.assertEqual("C", c["name"])
+        self.assertEqual("/// cls comment", c["doxygen"])
+
+    def test_cls2(self):
+        c = self.cppHeader.classes["C2"]
+        self.assertEqual("C2", c["name"])
+        self.assertEqual("/// template comment", c["doxygen"])
+
+
 if __name__ == "__main__":
     unittest.main()
