Improved doc-strings.

(cherry picked from commit 54ce76e3938413f9ee7d823cf63611c4ff5d8faf)

1 files changed, 33 insertions, 9 deletions

diff --git a/pyGHDL/dom/_Utils.py b/pyGHDL/dom/_Utils.py
index d8cd9a15c..22468d988 100644
--- a/pyGHDL/dom/_Utils.py
+++ b/pyGHDL/dom/_Utils.py
@@ -49,17 +49,30 @@ __MODE_TRANSLATION = {
     nodes.Iir_Mode.Buffer_Mode: Mode.Buffer,
     nodes.Iir_Mode.Linkage_Mode: Mode.Linkage,
 }
-
+"""
+Translation table if IIR modes to pyVHDLModel mode enumeration values.
+"""
 
 @export
 def CheckForErrors() -> None:
+    """
+    Check if an error occurred in libghdl and raise an exception if so.
+
+    **Behavior:**
+
+    1. read the error buffer and clear it afterwards
+    2. convert it into a list of internal messages for a :exc:`LibGHDLException`
+    3. raise a :exc:`DOMException` with a nested :exc:`LibGHDLException` as a ``__cause__``.
+
+    :raises DOMException: If an error occurred in libghdl.
+    """
     errorCount = errorout_memory.Get_Nbr_Messages()
-    errors = []
     if errorCount != 0:
+        errors = []
         for i in range(errorCount):
             rec = errorout_memory.Get_Error_Record(i + 1)
             # FIXME: needs help from @tgingold
-            fileName = ""  # name_table.Get_Name_Ptr(files_map.Get_File_Name(rec.file))
+            fileName = "????"  # name_table.Get_Name_Ptr(files_map.Get_File_Name(rec.file))
             message = errorout_memory.Get_Error_Message(i + 1)
 
             errors.append(f"{fileName}:{rec.line}:{rec.offset}: {message}")
@@ -71,9 +84,13 @@ def CheckForErrors() -> None:
 
 @export
 def GetIirKindOfNode(node: Iir) -> nodes.Iir_Kind:
-    """Return the kind of a node in the IIR tree."""
+    """Return the kind of a node in the IIR tree.
+
+    :returns:           The IIR kind of a node.
+    :raises ValueError: If parameter ``node`` is :py:data:`~pyGHDL.libghdl.vhdl.nodes.Null_Iir`.
+    """
     if node == Null_Iir:
-        raise ValueError("GetIirKindOfNode: Parameter 'node' must not be 'Null_iir'.")
+        raise ValueError("GetIirKindOfNode: Parameter 'node' must not be 'Null_Iir'.")
 
     kind: int = nodes.Get_Kind(node)
     return nodes.Iir_Kind(kind)
@@ -81,9 +98,12 @@ def GetIirKindOfNode(node: Iir) -> nodes.Iir_Kind:
 
 @export
 def GetNameOfNode(node: Iir) -> str:
-    """Return the python string from node :obj:`node` identifier."""
+    """Return the Python string from node ``node`` identifier.
+
+    :raises ValueError: If parameter ``node`` is :py:data:`~pyGHDL.libghdl.vhdl.nodes.Null_Iir`.
+    """
     if node == Null_Iir:
-        raise ValueError("GetNameOfNode: Parameter 'node' must not be 'Null_iir'.")
+        raise ValueError("GetNameOfNode: Parameter 'node' must not be 'Null_Iir'.")
 
     identifier = utils.Get_Source_Identifier(node)
     return name_table.Get_Name_Ptr(identifier)
@@ -103,9 +123,13 @@ def GetDocumentationOfNode(node: Iir) -> str:
 
 @export
 def GetModeOfNode(node: Iir) -> Mode:
-    """Return the mode of a :obj:`node`."""
+    """Return the mode of a ``node``.
+
+    :raises ValueError:   If parameter ``node`` is :py:data:`~pyGHDL.libghdl.vhdl.nodes.Null_Iir`.
+    :raises DOMException: If mode returned by libghdl is not known by :py:data:`__MODE_TRANSLATION`.
+    """
     if node == Null_Iir:
-        raise ValueError("GetModeOfNode: Parameter 'node' must not be 'Null_iir'.")
+        raise ValueError("GetModeOfNode: Parameter 'node' must not be 'Null_Iir'.")
 
     try:
         return __MODE_TRANSLATION[nodes.Get_Mode(node)]