From f0f7b022b35aac03d586fd23b1ee6700cca60bcf Mon Sep 17 00:00:00 2001
From: Patrick Lehmann <Patrick.Lehmann@plc2.de>
Date: Fri, 24 Jun 2022 23:20:48 +0200
Subject: Improved doc-strings.

(cherry picked from commit 54ce76e3938413f9ee7d823cf63611c4ff5d8faf)
---
 pyGHDL/dom/_Utils.py         | 42 +++++++++++++++++++++++++++++++++---------
 pyGHDL/libghdl/flags.py      | 14 ++++++++++++++
 pyGHDL/libghdl/vhdl/nodes.py |  3 +++
 3 files changed, 50 insertions(+), 9 deletions(-)

(limited to 'pyGHDL')

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)]
diff --git a/pyGHDL/libghdl/flags.py b/pyGHDL/libghdl/flags.py
index 4bf30ef50..4e5f73d00 100644
--- a/pyGHDL/libghdl/flags.py
+++ b/pyGHDL/libghdl/flags.py
@@ -50,6 +50,20 @@ __all__ = [
 
 assert sizeof(c_bool) == 1
 
+
+@export
+@unique
+class VhdlStandard(IntEnum):
+    """An enumeration representing libghdl's internal ``Vhdl_Std_Type`` enumeration type."""
+
+    Vhdl_87 = 0   #: VHDL'87
+    Vhdl_93 = 1   #: VHDL'93
+    Vhdl_00 = 2   #: VHDL'2000
+    Vhdl_02 = 3   #: VHDL'2002
+    Vhdl_08 = 4   #: VHDL'2008
+    Vhdl_19 = 5   #: VHDL'2019
+
+    
 Flag_Elocations = c_bool.in_dll(libghdl, "flags__flag_elocations")
 
 Verbose = c_bool.in_dll(libghdl, "flags__verbose")  #: Internal boolean flag representing :option:`-v`.
diff --git a/pyGHDL/libghdl/vhdl/nodes.py b/pyGHDL/libghdl/vhdl/nodes.py
index f662ad6a7..85c064c37 100644
--- a/pyGHDL/libghdl/vhdl/nodes.py
+++ b/pyGHDL/libghdl/vhdl/nodes.py
@@ -30,6 +30,9 @@ from pyGHDL.libghdl._types import (
 from pyGHDL.libghdl.vhdl.tokens import Tok
 
 Null_Iir = 0
+"""
+Null element for an IIR node reference.
+"""
 
 Null_Iir_List = 0
 Iir_List_All = 1
-- 
cgit v1.2.3