testsuite/pyunit: add more tests for comments

16 files changed, 311 insertions, 25 deletions

diff --git a/testsuite/pyunit/libghdl/Comment2.vhdl b/testsuite/pyunit/libghdl/Comment2.vhdl
new file mode 100644
index 000000000..e56815a52
--- /dev/null
+++ b/testsuite/pyunit/libghdl/Comment2.vhdl
@@ -0,0 +1,132 @@
+-- comments before design units (javadoc / .net documentation style)
+-- might be multiline
+entity e1 is
+end entity;
+
+-- comments before design units
+-- might be multiline
+architecture a1 of e1 is
+begin
+end architecture;
+
+-- comments before design units
+-- might be multiline
+package p1 is
+end package;
+
+-- package body should be supported too to keep parity, but I have currently no usecase for it.
+
+-- comments before design units
+-- might be multiline
+context ctx1 is
+end context;
+
+-- comments before design units
+-- might be multiline
+configuration cfg1 of e1 is
+  for a1
+  end for;
+end configuration;
+
+
+library ieee;
+use ieee.std_logic_1164.all;
+
+entity e2 is
+  -- comments in design units (python doc-string style)
+    -- might be multi line
+    generic (
+      -- comment before a generic
+        -- might be multiline
+        constant FREQUENCY : positive;
+      constant BITS      : positive; -- comment after a generic are mostly single line,
+                                       -- but could be multi line too
+        -- in case comment is before and after
+        constant DEBUG     : boolean   -- the after has presidence
+    );
+    port (
+      signal Clock : in std_logic    -- same as for generics
+    );
+end entity;
+
+architecture a2 of e2 is
+  -- comments in design units (python doc-string style)
+    -- might be multi line
+begin
+
+end architecture;
+
+-- As packages define public elements like constants, types and sub-programs, we are intrested in such documentation too.
+package p2 is
+  -- comments in design units (python doc-string style)
+    -- might be multi line
+
+    -- comment before
+    constant DEBUG : boolean := TRUE;
+    constant SYNC_STAGES : positive := 3; -- comment after
+
+    -- comment before
+    type AType1 is array(natural range <>) of bit;
+    type AType2 is array(natural range <>) of bit; -- comment after
+
+    -- same applies to subtype, alias, attributes, ...
+
+    -- comment before
+    type RType is record
+        -- xor comment inside
+
+        -- per element comment before (note the comment "block" is separated by newlines)
+        elem1 : integer;
+        elem2 : integer; -- per element comment behind
+    end record;
+
+    -- as functions are longer in definitions, it might be written before
+    function log2(param : positive) return natural;
+
+    function log2(
+        -- otoh, we also want to document parameters too (similar to a record with comments)
+
+      -- comment before
+      param1 : integer;
+        param2 : boolean  -- comment after
+    ) return natural;
+
+    -- this applies to procedures as well.
+
+
+
+end package;
+
+context ctx2 is
+  -- comments in design units (python doc-string style)
+    -- might be multi line
+end context;
+
+configuration cfg2 of e2 is
+  -- comments in design units (python doc-string style)
+  -- might be multi line
+  for a2
+  end for;
+end configuration;
+
+
+
+
+
+
+
+-- This should allow for any kind of documentation style and embedded documentation language.
+-- A real implementation might use similar rules are Python+docutils+Sphinx. Here we would e.g.
+-- document a function either before (or inside) a function declaration and use the
+--   :arg name: description
+-- syntax.
+
+
+-- Package `math` provides math extensions not provided by the IEEE packages.
+package math is
+    -- Computes the logarith to base 2.
+    --
+    -- :arg param: Input value
+    -- :returns:   Logarithm
+    function log2(param : positive) return natural;
+end package;
diff --git a/testsuite/pyunit/libghdl/Comments.py b/testsuite/pyunit/libghdl/Comments.py
index ada8f326e..9a4daf007 100644
--- a/testsuite/pyunit/libghdl/Comments.py
+++ b/testsuite/pyunit/libghdl/Comments.py
@@ -1,5 +1,5 @@
 from pathlib import Path
-from unittest import TestCase
+from unittest import TestCase, skip, expectedFailure
 
 import pyGHDL.libghdl as libghdl
 from pyGHDL.libghdl import name_table, files_map, errorout_console, flags
@@ -13,25 +13,15 @@ if __name__ == "__main__":
 
 
 class Instantiate(TestCase):
-    _root = Path(__file__).resolve().parent.parent
-    _filename: Path = _root / "DesignComment.vhdl"
+    _root = Path(__file__).resolve().parent
 
     @staticmethod
     def getIdentifier(node) -> str:
         """Return the Python string from node :obj:`node` identifier."""
         return name_table.Get_Name_Ptr(nodes.Get_Identifier(node))
 
-    def checkComments(self, node, name) -> None:
-        f = files_map.Location_To_File(nodes.Get_Location(node))
-        idx = file_comments.Find_First_Comment(f, node)
-        while idx != file_comments.No_Comment_Index:
-            s = file_comments.Get_Comment(f, idx)
-            self.assertTrue(s.find(':'+name+':') >= 0,
-                            "no :{}: in '{}'".format(name, s))
-            idx = file_comments.Get_Next_Comment(f, idx)
-
-    def test_Comments(self) -> None:
-        """Initialization: set options and then load libaries."""
+    @classmethod
+    def setUpClass(cls):
         libghdl.initialize()
 
         # Print error messages on the console.
@@ -45,11 +35,27 @@ class Instantiate(TestCase):
         if libghdl.analyze_init_status() != 0:
             self.fail("libghdl initialization error")
 
+    def checkComments(self, node, name) -> None:
+        f = files_map.Location_To_File(nodes.Get_Location(node))
+        idx = file_comments.Find_First_Comment(f, node)
+        while idx != file_comments.No_Comment_Index:
+            s = file_comments.Get_Comment(f, idx)
+            self.assertTrue(s.find(':'+name+':') >= 0,
+                            "no :{}: in '{}'".format(name, s))
+            idx = file_comments.Get_Next_Comment(f, idx)
+
+    def checkInterfaces(self, first) -> None:
+        inter = first
+        while inter != nodes.Null_Iir:
+            self.checkComments(inter, self.getIdentifier(inter))
+            inter = nodes.Get_Chain(inter)
+
+    def checkFile(self, filename) -> None:
         # Load the file
-        file_id = name_table.Get_Identifier(str(self._filename))
+        file_id = name_table.Get_Identifier(str(filename))
         sfe = files_map.Read_Source_File(name_table.Null_Identifier, file_id)
         if sfe == files_map.No_Source_File_Entry:
-            self.fail("Cannot read file '{!s}'".format(self._filename))
+            self.fail("Cannot read file '{!s}'".format(filename))
 
         # Parse
         file = sem_lib.Load_File(sfe)
@@ -59,18 +65,87 @@ class Instantiate(TestCase):
         while designUnit != nodes.Null_Iir:
             libraryUnit = nodes.Get_Library_Unit(designUnit)
 
-            if nodes.Get_Kind(libraryUnit) == nodes.Iir_Kind.Entity_Declaration:
-                entityName = self.getIdentifier(libraryUnit)
-                self.checkComments(designUnit, entityName)
-                port = nodes.Get_Port_Chain(libraryUnit)
-                while port != nodes.Null_Iir:
-                    self.checkComments(port, self.getIdentifier(port))
-                    port = nodes.Get_Chain(port)
+            k = nodes.Get_Kind(libraryUnit)
+            name = self.getIdentifier(libraryUnit)
+
+            if k == nodes.Iir_Kind.Entity_Declaration:
+                self.checkComments(designUnit, name)
+                self.checkComments(libraryUnit, name)
+                self.checkInterfaces(nodes.Get_Generic_Chain(libraryUnit))
+                self.checkInterfaces(nodes.Get_Port_Chain(libraryUnit))
 
-            elif nodes.Get_Kind(libraryUnit) == nodes.Iir_Kind.Architecture_Body:
-                architectureName = self.getIdentifier(libraryUnit)
+            elif k == nodes.Iir_Kind.Architecture_Body:
+                self.checkComments(designUnit, name)
+                self.checkComments(libraryUnit, name)
+
+            elif k == nodes.Iir_Kind.Package_Declaration:
+                self.checkComments(designUnit, name)
+                self.checkComments(libraryUnit, name)
+
+            elif k == nodes.Iir_Kind.Context_Declaration:
+                self.checkComments(designUnit, name)
+                self.checkComments(libraryUnit, name)
+
+            elif k == nodes.Iir_Kind.Configuration_Declaration:
+                self.checkComments(designUnit, name)
+                self.checkComments(libraryUnit, name)
 
             else:
                 self.fail("Unknown unit.")
 
             designUnit = nodes.Get_Chain(designUnit)
+
+    def test_Comments(self) -> None:
+        """Very first test"""
+        self.checkFile(self._root / "DesignComment.vhdl")
+
+    @skip("not yet handled")
+    def test_Comment2(self) -> None:
+        """More exhaustive"""
+        self.checkFile(self._root / "Comment2.vhdl")
+
+    def test_entity_before(self) -> None:
+        self.checkFile(self._root / "ent_bef.vhdl")
+
+    def test_arch_before(self) -> None:
+        self.checkFile(self._root / "arch_bef.vhdl")
+
+    def test_pkg_before(self) -> None:
+        self.checkFile(self._root / "pkg_bef.vhdl")
+
+    def test_ctxt_before(self) -> None:
+        self.checkFile(self._root / "ctxt_bef.vhdl")
+
+    def test_conf_before(self) -> None:
+        self.checkFile(self._root / "conf_bef.vhdl")
+
+    def test_entity_inside(self) -> None:
+        self.checkFile(self._root / "ent_inside.vhdl")
+
+    @expectedFailure
+    def test_arch_inside_fail(self) -> None:
+        self.checkFile(self._root / "arch_inside_fail.vhdl")
+
+    def test_arch_inside(self) -> None:
+        self.checkFile(self._root / "arch_inside.vhdl")
+
+    @expectedFailure
+    def test_pkg_inside_fail(self) -> None:
+        self.checkFile(self._root / "pkg_inside_fail.vhdl")
+
+    def test_pkg_inside(self) -> None:
+        self.checkFile(self._root / "pkg_inside.vhdl")
+
+    @expectedFailure
+    def test_ctxt_inside_fail(self) -> None:
+        self.checkFile(self._root / "ctxt_inside_fail.vhdl")
+
+    def test_ctxt_inside(self) -> None:
+        self.checkFile(self._root / "ctxt_inside.vhdl")
+
+    @expectedFailure
+    def test_conf_inside_fail(self) -> None:
+        self.checkFile(self._root / "conf_inside_fail.vhdl")
+
+    def test_conf_inside(self) -> None:
+        self.checkFile(self._root / "conf_inside.vhdl")
diff --git a/testsuite/pyunit/libghdl/arch_bef.vhdl b/testsuite/pyunit/libghdl/arch_bef.vhdl
new file mode 100644
index 000000000..c089b1429
--- /dev/null
+++ b/testsuite/pyunit/libghdl/arch_bef.vhdl
@@ -0,0 +1,5 @@
+-- comments before design units :a1:
+-- might be multiline :a1:
+architecture a1 of e1 is
+begin
+end architecture;
diff --git a/testsuite/pyunit/libghdl/arch_inside.vhdl b/testsuite/pyunit/libghdl/arch_inside.vhdl
new file mode 100644
index 000000000..9e2184df3
--- /dev/null
+++ b/testsuite/pyunit/libghdl/arch_inside.vhdl
@@ -0,0 +1,6 @@
+architecture a2 of e2 is
+  -- comments in design units (python doc-string style) :a2:
+    --:a2: might be multi line
+begin
+
+end architecture;
diff --git a/testsuite/pyunit/libghdl/arch_inside_fail.vhdl b/testsuite/pyunit/libghdl/arch_inside_fail.vhdl
new file mode 100644
index 000000000..96002d336
--- /dev/null
+++ b/testsuite/pyunit/libghdl/arch_inside_fail.vhdl
@@ -0,0 +1,5 @@
+architecture a2 of e2 is
+  -- comments in design units (python doc-string style) :fail:
+begin
+
+end architecture;
diff --git a/testsuite/pyunit/libghdl/conf_bef.vhdl b/testsuite/pyunit/libghdl/conf_bef.vhdl
new file mode 100644
index 000000000..0dc3af77e
--- /dev/null
+++ b/testsuite/pyunit/libghdl/conf_bef.vhdl
@@ -0,0 +1,6 @@
+-- comments before design units :cfg1:
+-- might be multiline :cfg1:
+configuration cfg1 of e1 is
+  for a1
+  end for;
+end configuration;
diff --git a/testsuite/pyunit/libghdl/conf_inside.vhdl b/testsuite/pyunit/libghdl/conf_inside.vhdl
new file mode 100644
index 000000000..6181d572a
--- /dev/null
+++ b/testsuite/pyunit/libghdl/conf_inside.vhdl
@@ -0,0 +1,6 @@
+configuration cfg2 of e2 is
+  -- comments in design units (python doc-string style) :cfg2:
+  -- might be multi line :cfg2:
+  for a2
+  end for;
+end configuration;
diff --git a/testsuite/pyunit/libghdl/conf_inside_fail.vhdl b/testsuite/pyunit/libghdl/conf_inside_fail.vhdl
new file mode 100644
index 000000000..6b9b4dce3
--- /dev/null
+++ b/testsuite/pyunit/libghdl/conf_inside_fail.vhdl
@@ -0,0 +1,6 @@
+configuration cfg2 of e2 is
+  -- comments in design units (python doc-string style)
+  -- might be multi line
+  for a2
+  end for;
+end configuration;
diff --git a/testsuite/pyunit/libghdl/ctxt_bef.vhdl b/testsuite/pyunit/libghdl/ctxt_bef.vhdl
new file mode 100644
index 000000000..f7a8fd31c
--- /dev/null
+++ b/testsuite/pyunit/libghdl/ctxt_bef.vhdl
@@ -0,0 +1,4 @@
+-- comments before design units :ctx1:
+--:ctx1: might be multiline
+context ctx1 is
+end context;
diff --git a/testsuite/pyunit/libghdl/ctxt_inside.vhdl b/testsuite/pyunit/libghdl/ctxt_inside.vhdl
new file mode 100644
index 000000000..af7fdc37b
--- /dev/null
+++ b/testsuite/pyunit/libghdl/ctxt_inside.vhdl
@@ -0,0 +1,5 @@
+context ctx2 is
+  -- comments in design units (python doc-string style) :ctx2:
+    -- might be multi line :ctx2:
+end context;
+
diff --git a/testsuite/pyunit/libghdl/ctxt_inside_fail.vhdl b/testsuite/pyunit/libghdl/ctxt_inside_fail.vhdl
new file mode 100644
index 000000000..71dce9e40
--- /dev/null
+++ b/testsuite/pyunit/libghdl/ctxt_inside_fail.vhdl
@@ -0,0 +1,5 @@
+context ctx2 is
+  -- comments in design units (python doc-string style)
+    -- might be multi line
+end context;
+
diff --git a/testsuite/pyunit/libghdl/ent_bef.vhdl b/testsuite/pyunit/libghdl/ent_bef.vhdl
new file mode 100644
index 000000000..0fbf61d22
--- /dev/null
+++ b/testsuite/pyunit/libghdl/ent_bef.vhdl
@@ -0,0 +1,4 @@
+-- comments before design units (javadoc / .net documentation style) :e1:
+-- might be multiline :e1:
+entity e1 is
+end entity;
diff --git a/testsuite/pyunit/libghdl/ent_inside.vhdl b/testsuite/pyunit/libghdl/ent_inside.vhdl
new file mode 100644
index 000000000..834eaa999
--- /dev/null
+++ b/testsuite/pyunit/libghdl/ent_inside.vhdl
@@ -0,0 +1,15 @@
+library ieee;
+use ieee.std_logic_1164.all;
+
+entity e2 is
+  -- comments in design units (python doc-string style) :e2:
+    -- might be multi line :e2:
+    generic (
+      -- comment before a generic :frequency:
+        -- might be multiline :frequency:
+        constant FREQUENCY : positive
+    );
+    port (
+      signal Clock : in std_logic
+    );
+end entity;
diff --git a/testsuite/pyunit/libghdl/pkg_bef.vhdl b/testsuite/pyunit/libghdl/pkg_bef.vhdl
new file mode 100644
index 000000000..1ed150346
--- /dev/null
+++ b/testsuite/pyunit/libghdl/pkg_bef.vhdl
@@ -0,0 +1,4 @@
+-- comments before design units :p1:
+-- :p1: might be multiline
+package p1 is
+end package;
diff --git a/testsuite/pyunit/libghdl/pkg_inside.vhdl b/testsuite/pyunit/libghdl/pkg_inside.vhdl
new file mode 100644
index 000000000..c9f6129d4
--- /dev/null
+++ b/testsuite/pyunit/libghdl/pkg_inside.vhdl
@@ -0,0 +1,5 @@
+-- As packages define public elements like constants, types and sub-programs, we are intrested in such documentation too.:p2:
+package p2 is
+  -- comments in design units (python doc-string style):p2:
+    -- might be multi line :p2:
+end package;
diff --git a/testsuite/pyunit/libghdl/pkg_inside_fail.vhdl b/testsuite/pyunit/libghdl/pkg_inside_fail.vhdl
new file mode 100644
index 000000000..f5e347488
--- /dev/null
+++ b/testsuite/pyunit/libghdl/pkg_inside_fail.vhdl
@@ -0,0 +1,3 @@
+package p2 is
+  -- comments in design units (python doc-string style) :fail:
+end package;