Added one-line code documentations.

5 files changed, 28 insertions, 5 deletions

diff --git a/pyGHDL/dom/formatting/prettyprint.py b/pyGHDL/dom/formatting/prettyprint.py
index 26a964aec..7c99e1d87 100644
--- a/pyGHDL/dom/formatting/prettyprint.py
+++ b/pyGHDL/dom/formatting/prettyprint.py
@@ -114,6 +114,14 @@ class PrettyPrint:
     # def __init__(self):
     #     self._buffer = []
 
+    def CleanupDocumentationBlocks(self, documentationContent: str,  level: int = 0):
+        prefix = "  " * level
+        if documentationContent is None:
+            return prefix
+
+        documentationLines = documentationContent.split("\n")
+        return f"{prefix}{documentationLines[0][2:].lstrip()}"
+
     def formatDesign(self, design: Design, level: int = 0) -> StringBuffer:
         buffer = []
         prefix = "  " * level
@@ -190,10 +198,12 @@ class PrettyPrint:
     def formatEntity(self, entity: Entity, level: int = 0) -> StringBuffer:
         buffer = []
         prefix = "  " * level
+        documentationFirstLine = self.CleanupDocumentationBlocks(entity.Documentation)
         buffer.append(
             f"{prefix}- Name: {entity.Identifier}\n"
             f"{prefix}  File: {entity.Position.Filename.name}\n"
-            f"{prefix}  Position: {entity.Position.Line}:{entity.Position.Column}"
+            f"{prefix}  Position: {entity.Position.Line}:{entity.Position.Column}\n"
+            f"{prefix}  Documentation: {documentationFirstLine}"
         )
         buffer.append(f"{prefix}  Generics:")
         for generic in entity.GenericItems:
@@ -219,10 +229,12 @@ class PrettyPrint:
     def formatArchitecture(self, architecture: Architecture, level: int = 0) -> StringBuffer:
         buffer = []
         prefix = "  " * level
+        documentationFirstLine = self.CleanupDocumentationBlocks(architecture.Documentation)
         buffer.append(
             f"{prefix}- Name: {architecture.Identifier}\n"
             f"{prefix}  File: {architecture.Position.Filename.name}\n"
-            f"{prefix}  Position: {architecture.Position.Line}:{architecture.Position.Column}"
+            f"{prefix}  Position: {architecture.Position.Line}:{architecture.Position.Column}\n"
+            f"{prefix}  Documentation: {documentationFirstLine}"
         )
         buffer.append(f"{prefix}  Entity: {architecture.Entity.SymbolName}")
         buffer.append(f"{prefix}  Declared:")
@@ -244,6 +256,7 @@ class PrettyPrint:
     def formatComponent(self, component: Component, level: int = 0) -> StringBuffer:
         buffer = []
         prefix = "  " * level
+        documentationFirstLine = self.CleanupDocumentationBlocks(component.Documentation)
         buffer.append(f"{prefix}- Component: {component.Identifier}")
         buffer.append(f"{prefix}  Generics:")
         for generic in component.GenericItems:
@@ -259,10 +272,12 @@ class PrettyPrint:
     def formatPackage(self, package: Package, level: int = 0) -> StringBuffer:
         buffer = []
         prefix = "  " * level
+        documentationFirstLine = self.CleanupDocumentationBlocks(package.Documentation)
         buffer.append(
             f"{prefix}- Name: {package.Identifier}\n"
             f"{prefix}  File: {package.Position.Filename.name}\n"
-            f"{prefix}  Position: {package.Position.Line}:{package.Position.Column}"
+            f"{prefix}  Position: {package.Position.Line}:{package.Position.Column}\n"
+            f"{prefix}  Documentation: {documentationFirstLine}"
         )
         buffer.append(f"{prefix}  Declared:")
         for item in package.DeclaredItems:
@@ -274,6 +289,7 @@ class PrettyPrint:
     def formatPackageInstance(self, package: PackageInstantiation, level: int = 0) -> StringBuffer:
         buffer = []
         prefix = "  " * level
+        documentationFirstLine = self.CleanupDocumentationBlocks(package.Documentation)
         buffer.append(f"{prefix}- Name: {package.Identifier}")
         buffer.append(f"{prefix}  Package: {package.PackageReference!s}")
         buffer.append(f"{prefix}  Generic Map: ...")
@@ -286,7 +302,11 @@ class PrettyPrint:
     def formatPackageBody(self, packageBody: PackageBody, level: int = 0) -> StringBuffer:
         buffer = []
         prefix = "  " * level
-        buffer.append(f"{prefix}- Name: {packageBody.Identifier}")
+        documentationFirstLine = self.CleanupDocumentationBlocks(packageBody.Documentation)
+        buffer.append(
+            f"{prefix}- Name: {packageBody.Identifier}\n"
+            f"{prefix}  Documentation: {documentationFirstLine}"
+        )
         buffer.append(f"{prefix}  Declared:")
         for item in packageBody.DeclaredItems:
             for line in self.formatDeclaredItems(item, level + 1):
diff --git a/testsuite/pyunit/dom/examples/StopWatch/StopWatch.pkg.vhdl b/testsuite/pyunit/dom/examples/StopWatch/StopWatch.pkg.vhdl
index 3bcafdd6d..1a40718aa 100644
--- a/testsuite/pyunit/dom/examples/StopWatch/StopWatch.pkg.vhdl
+++ b/testsuite/pyunit/dom/examples/StopWatch/StopWatch.pkg.vhdl
@@ -7,7 +7,7 @@ library IEEE;
 use     IEEE.std_logic_1164.all;
 use     IEEE.numeric_std.all;
 
-
+-- Package with stop watch specific types.
 package StopWatch_pkg is
 	subtype T_BCD is unsigned(3 downto 0);
 	type T_BCD_Vector is array(natural range <>) of T_BCD;
diff --git a/testsuite/pyunit/dom/examples/StopWatch/Utilities.pkg.vhdl b/testsuite/pyunit/dom/examples/StopWatch/Utilities.pkg.vhdl
index 8daf39614..16a40ccba 100644
--- a/testsuite/pyunit/dom/examples/StopWatch/Utilities.pkg.vhdl
+++ b/testsuite/pyunit/dom/examples/StopWatch/Utilities.pkg.vhdl
@@ -8,6 +8,7 @@ use     IEEE.std_logic_1164.all;
 use     IEEE.numeric_std.all;
 
 
+-- Useful utility functions and types.
 package Utilities is
 	type freq is range integer'low to integer'high units
 		Hz;
diff --git a/testsuite/pyunit/dom/examples/StopWatch/seg7_Encoder.vhdl b/testsuite/pyunit/dom/examples/StopWatch/seg7_Encoder.vhdl
index e4c731ff9..3742982be 100644
--- a/testsuite/pyunit/dom/examples/StopWatch/seg7_Encoder.vhdl
+++ b/testsuite/pyunit/dom/examples/StopWatch/seg7_Encoder.vhdl
@@ -11,6 +11,7 @@ use     work.Utilities.all;
 use     work.StopWatch_pkg.all;
 
 
+-- Encoder that translates from 4-bit binary (BCD) to 7-segment code.
 entity seg7_Encoder is
 	port (
 		BCDValue  : in  T_BCD;
diff --git a/testsuite/pyunit/dom/examples/StopWatch/toplevel.Encoder.vhdl b/testsuite/pyunit/dom/examples/StopWatch/toplevel.Encoder.vhdl
index 7775a6eb6..58294b67f 100644
--- a/testsuite/pyunit/dom/examples/StopWatch/toplevel.Encoder.vhdl
+++ b/testsuite/pyunit/dom/examples/StopWatch/toplevel.Encoder.vhdl
@@ -11,6 +11,7 @@ use     work.Utilities.all;
 use     work.StopWatch_pkg.all;
 
 
+-- Toplevel module to demonstrate the translation of 4 slide-switches to 1 digit 7-segment display.
 entity toplevel is
 	port (
 		NexysA7_GPIO_Switch         : in  std_logic_vector(3 downto 0);