Improved docs-strings.

(cherry picked from commit 6979b2846e07791629f7f6011145f5886abfee33)

3 files changed, 26 insertions, 14 deletions

diff --git a/pyGHDL/__init__.py b/pyGHDL/__init__.py
index 64a3c3d87..4e8bc2ca8 100644
--- a/pyGHDL/__init__.py
+++ b/pyGHDL/__init__.py
@@ -38,13 +38,13 @@
 GHDL offers two Python interfaces and a language server protocol service. All
 this is provided from a ``pyGHDL`` packages with four sub-packages:
 
-* ``pyGHDL.cli`` - Command line interface (CLI) applications.
-* ``pyGHDL.dom`` - A high-level API offering a document object model (DOM).
+* :mod:`pyGHDL.cli` - Command line interface (CLI) applications.
+* :mod:`pyGHDL.dom` - A high-level API offering a document object model (DOM).
   The underlying abstract VHDL language model is provided by :doc:`pyVHDLModel <vhdlmodel:index>`.
   The DOM is using ``libghdl`` for file analysis and parsing.
-* ``pyGHDL.libghdl`` - A low-level API directly interacting with the shared library ``libghdl....so``/``libghdl....dll``.
+* :mod:`pyGHDL.libghdl` - A low-level API directly interacting with the shared library ``libghdl....so``/``libghdl....dll``.
   This is a procedural and C-like interface. It comes with some Python generators for easier iterating linked lists.
-* ``pyGHDL.lsp`` - A :wikipedia:`language server protocol <Language_Server_Protocol>` (LSP)
+* :mod:`pyGHDL.lsp` - A :wikipedia:`language server protocol <Language_Server_Protocol>` (LSP)
   written in Python. The implementation offers an HTTPS service that can be used e.g. by editors and IDEs supporting LSP.
 """
 __author__ = "Tristan Gingold and contributors"
diff --git a/pyGHDL/dom/__init__.py b/pyGHDL/dom/__init__.py
index 12caccc1b..e60a4e211 100644
--- a/pyGHDL/dom/__init__.py
+++ b/pyGHDL/dom/__init__.py
@@ -9,8 +9,6 @@
 # Authors:
 #   Patrick Lehmann
 #
-# Package package:  Document object model (DOM) for pyGHDL.libghdl.
-#
 # License:
 # ============================================================================
 #  Copyright (C) 2019-2021 Tristan Gingold
@@ -30,6 +28,9 @@
 #
 # SPDX-License-Identifier: GPL-2.0-or-later
 # ============================================================================
+"""
+Document object model (DOM) for :mod:`pyGHDL.libghdl` based on :doc:`pyVHDLModel <vhdlmodel:index>`.
+"""
 from pathlib import Path
 
 from pyTooling.Decorators import export
diff --git a/pyGHDL/libghdl/__init__.py b/pyGHDL/libghdl/__init__.py
index 2cf9cff70..2be39d1d6 100644
--- a/pyGHDL/libghdl/__init__.py
+++ b/pyGHDL/libghdl/__init__.py
@@ -10,11 +10,9 @@
 #   Tristan Gingold
 #   Patrick Lehmann
 #
-# Package package:  Python binding and low-level API for shared library 'libghdl'.
-#
 # License:
 # ============================================================================
-#  Copyright (C) 2019-2021 Tristan Gingold
+#  Copyright (C) 2019-2022 Tristan Gingold
 #
 #  This program is free software: you can redistribute it and/or modify
 #  it under the terms of the GNU General Public License as published by
@@ -31,6 +29,11 @@
 #
 # SPDX-License-Identifier: GPL-2.0-or-later
 # ============================================================================
+"""
+Python binding and low-level API for shared library ``libghdl``.
+
+In case of an error, a :exc:`LibGHDLException` is raised.
+"""
 from ctypes import c_char_p, CDLL
 from sys import platform as sys_platform, version_info as sys_version_info
 from os import environ as os_environ
@@ -48,9 +51,12 @@ from pyGHDL import __version__ as ghdlVersion
 
 Nullable = Optional
 
+__all__ = ["ENCODING"]
+
 ENCODING = "latin-1"
 
 
+@export
 class LibGHDLException(GHDLBaseException):
     _internalErrors: Nullable[List[str]]
 
@@ -63,6 +69,7 @@ class LibGHDLException(GHDLBaseException):
         return self._internalErrors
 
 
+@export
 def _get_libghdl_name() -> Path:
     """Get the name of the libghdl library (with version and extension)."""
     version = ghdlVersion.replace("-", "_").replace(".", "_")
@@ -70,6 +77,7 @@ def _get_libghdl_name() -> Path:
     return Path(f"libghdl-{version}.{ext}")
 
 
+@export
 def _check_libghdl_libdir(libdir: Path, basename: Path) -> Path:
     """Returns libghdl path in :obj:`libdir`, if found."""
     if libdir is None:
@@ -82,6 +90,7 @@ def _check_libghdl_libdir(libdir: Path, basename: Path) -> Path:
     raise FileNotFoundError(str(res))
 
 
+@export
 def _check_libghdl_bindir(bindir: Path, basename: Path) -> Path:
     if bindir is None:
         raise ValueError("Parameter 'bindir' is None.")
@@ -89,11 +98,12 @@ def _check_libghdl_bindir(bindir: Path, basename: Path) -> Path:
     return _check_libghdl_libdir((bindir / "../lib").resolve(), basename)
 
 
+@export
 def _get_libghdl_path():
     """\
     Locate the directory where the shared library is installed.
 
-    Search order:
+    **Search order:**
 
     1. `GHDL_PREFIX` - directory (prefix) of the vhdl libraries.
     2. `VUNIT_GHDL_PATH` - path of the `ghdl` binary when using VUnit.
@@ -145,6 +155,7 @@ def _get_libghdl_path():
     raise Exception(f"Cannot find libghdl {basename}")
 
 
+@export
 def _initialize():
     # Load the shared library
     _libghdl_path = _get_libghdl_path()
@@ -192,15 +203,15 @@ def initialize() -> None:
 
 @export
 # @BindToLibGHDL("libghdl__set_option")
-def set_option(Opt: str) -> bool:
+def set_option(opt: str) -> bool:
     """\
     Set option :obj:`opt`.
 
-    :param Opt: Option to set.
+    :param opt: Option to set.
     :return:    Return ``True``, if the option is known and handled.
     """
-    Opt = Opt.encode(ENCODING)
-    return libghdl.libghdl__set_option(c_char_p(Opt), len(Opt)) == 0
+    opt = opt.encode(ENCODING)
+    return libghdl.libghdl__set_option(c_char_p(opt), len(opt)) == 0
 
 
 @export