WIP - Trying to match comments above a variable to it too

Author: RobertoRoos

src/plcdoc/interpreter.py

@@ -369,6 +369,9 @@ def get_comment(self) -> Optional[str]:
                 return None
 
             big_block: str = block_comment.text
+        elif hasattr(self._model, "comments_above") and self._model.comments_above is not None:
+            # Comment was put above it instead of inline
+            big_block: str = self._model.comments_above[-1].text
         else:
             return None
 

src/plcdoc/st_declaration.tx

@@ -157,9 +157,12 @@ VariableListType:
 Single variable declaration
 
 Unfortunately, it is possible to define multiple variables inline - those are ignored for now
+
+Inline comments after the variable are matched, but comments above it also. Because of priority
+comments above would have been caught by the preceding variable if relevant.
 */
 Variable:
-    CommentAny*
+    comments_above=CommentAny*
     name=ID
     (',' ID)*
     (address=Address)?

tests/plc_code/FB_Comments.txt

@@ -12,6 +12,8 @@ VAR_INPUT // Ignored
     someInput       : LREAL;  // Important
     // Ignored
     otherInput      : BOOL;                    // Important
+    // Important
+    lastInput       : INT;
 END_VAR
 // Ignored
 VAR_OUTPUT

tests/roots/test-plc-autodoc/src_plc/AutoFunction.TcPOU

@@ -11,6 +11,9 @@ FUNCTION AutoFunction : LREAL
 VAR_INPUT
     input       : LREAL;            // This is an in-code description of some variable
     other_arg   : UDINT;
+
+    // This is a comment above "above"
+    above       : BOOL;
 END_VAR
 VAR
 END_VAR

tests/test_plc_autodoc.py

@@ -70,7 +70,7 @@ def test_autodoc_function(app, status, warning):
 
     actual = do_autodoc(app, "plc:function", "AutoFunction")
 
-    assert ".. plc:function:: AutoFunction(input, other_arg)" in actual
+    assert ".. plc:function:: AutoFunction(input, other_arg, above)" in actual
 
     expected_end = [
         "   Short description of the function.",
@@ -80,10 +80,11 @@ def test_autodoc_function(app, status, warning):
         "",
         "   :var_input LREAL input: This is an in-code description of some variable",
         "   :var_input UDINT other_arg:",
+        '   :var_input BOOL above: This is a comment above "above"',
         "",
     ]
 
-    assert expected_end == actual[-8:]
+    assert list(actual)[-9:] == expected_end
 
 
 @pytest.mark.sphinx("html", testroot="plc-autodoc")

tests/test_st_grammar.py

@@ -168,8 +168,8 @@ def test_grammar_comments(meta_model):
     filepath = os.path.realpath(tests_dir + "/plc_code/" + filename)
     try:
         model = meta_model.model_from_file(filepath)
-    except:
-        pytest.fail(f"Error when analyzing the file `{filename}`")
+    except TextXSyntaxError as err:
+        pytest.fail(f"Error when analyzing the file `{filename}`: {err}")
     else:
         assert model is not None
         assert model.functions and not model.types
@@ -181,7 +181,7 @@ def test_grammar_comments(meta_model):
             "VAR_INPUT",
             "VAR_OUTPUT",
             "VAR",
-            "VAR",
+        "VAR",
         ]
         assert [l.constant for l in fb.lists] == [False, False, True, False]
 
@@ -190,6 +190,7 @@ def test_grammar_comments(meta_model):
             fb.comments[-1].text,
             fb.lists[0].variables[0].comment.text,
             fb.lists[0].variables[1].comment.text,
+            fb.lists[0].variables[2].comments_above[0].text,
             fb.lists[1].variables[0].comment.text,
             fb.lists[2].variables[0].comment.text,
             fb.lists[3].variables[0].comment.text,