Improved docstrings.

2 files changed, 118 insertions, 104 deletions

diff --git a/pyGHDL/libghdl/__init__.py b/pyGHDL/libghdl/__init__.py
index 1b400c5c1..030c1bea2 100644
--- a/pyGHDL/libghdl/__init__.py
+++ b/pyGHDL/libghdl/__init__.py
@@ -46,103 +46,103 @@ from pyGHDL.libghdl.version import __version__
 
 
 def _get_libghdl_name() -> Path:
-    """Get the name of the libghdl library (with version and extension)"""
-    ver = __version__.replace("-", "_").replace(".", "_")
-    ext = {"win32": "dll", "cygwin": "dll", "darwin": "dylib"}.get(sys.platform, "so")
-    return Path("libghdl-{version}.{ext}".format(version=ver, ext=ext))
+	"""Get the name of the libghdl library (with version and extension)"""
+	ver = __version__.replace("-", "_").replace(".", "_")
+	ext = {"win32": "dll", "cygwin": "dll", "darwin": "dylib"}.get(sys.platform, "so")
+	return Path("libghdl-{version}.{ext}".format(version=ver, ext=ext))
 
 
 def _check_libghdl_libdir(libdir: Path, basename: Path) -> Path:
-    """Returns libghdl path in :obj:`libdir`, if found."""
-    if libdir is None:
-        raise ValueError("Parameter 'libdir' is None.")
-    # print('libghdl: check in {}'.format(libdir))
-    res = libdir / basename
-    if res.exists():
-        return res
+	"""Returns libghdl path in :obj:`libdir`, if found."""
+	if libdir is None:
+		raise ValueError("Parameter 'libdir' is None.")
+	# print('libghdl: check in {}'.format(libdir))
+	res = libdir / basename
+	if res.exists():
+		return res
 
-    raise FileNotFoundError(str(res))
+	raise FileNotFoundError(str(res))
 
 
 def _check_libghdl_bindir(bindir: Path, basename: Path) -> Path:
-    if bindir is None:
-        raise ValueError("Parameter 'bindir' is None.")
+	if bindir is None:
+		raise ValueError("Parameter 'bindir' is None.")
 
-    return _check_libghdl_libdir((bindir / "../lib").resolve(), basename)
+	return _check_libghdl_libdir((bindir / "../lib").resolve(), basename)
 
 
 def _get_libghdl_path():
-    """
-    Locate the directory where the shared library is installed.
-
-    Search order:
-
-    1. `GHDL_PREFIX` - directory (prefix) of the vhdl libraries.
-    2. `VUNIT_GHDL_PATH` - path of the `ghdl` binary when using VUnit.
-    3. `GHDL` - name of, or path to the `ghdl` binary.
-    4. Try within `libghdl/` Python installation.
-    5. Try when running from the build directory.
-    """
-    basename = _get_libghdl_name()
-
-    # Try GHDL_PREFIX
-    # GHDL_PREFIX is the prefix of the vhdl libraries, so remove the
-    # last path component.
-    r = os.environ.get("GHDL_PREFIX")
-    try:
-        return _check_libghdl_libdir(Path(r).parent, basename)
-    except (TypeError, FileNotFoundError):
-        pass
-
-    # Try VUNIT_GHDL_PATH (path of the ghdl binary when using VUnit).
-    r = os.environ.get("VUNIT_GHDL_PATH")
-    try:
-      return _check_libghdl_bindir(Path(r), basename)
-    except (TypeError, FileNotFoundError):
-        pass
-
-    # Try GHDL (name/path of the ghdl binary)
-    r = os.environ.get("GHDL", "ghdl")
-    r = which(r)
-    try:
-        return _check_libghdl_bindir(Path(r).parent, basename)
-    except (TypeError, FileNotFoundError):
-        pass
-
-    # Try within libghdl/ python installation
-    r = Path(__file__)
-    try:
-        return _check_libghdl_bindir(r.parent, basename)
-    except (TypeError, FileNotFoundError):
-        pass
-
-    # Try when running from the build directory
-    r = (r.parent / "../../lib").resolve()
-    try:
-        return _check_libghdl_libdir(r, basename)
-    except (TypeError, FileNotFoundError):
-        pass
-
-    # Failed.
-    raise Exception("Cannot find libghdl {}".format(basename))
+	"""
+	Locate the directory where the shared library is installed.
+
+	Search order:
+
+	1. `GHDL_PREFIX` - directory (prefix) of the vhdl libraries.
+	2. `VUNIT_GHDL_PATH` - path of the `ghdl` binary when using VUnit.
+	3. `GHDL` - name of, or path to the `ghdl` binary.
+	4. Try within `libghdl/` Python installation.
+	5. Try when running from the build directory.
+	"""
+	basename = _get_libghdl_name()
+
+	# Try GHDL_PREFIX
+	# GHDL_PREFIX is the prefix of the vhdl libraries, so remove the
+	# last path component.
+	r = os.environ.get("GHDL_PREFIX")
+	try:
+	    return _check_libghdl_libdir(Path(r).parent, basename)
+	except (TypeError, FileNotFoundError):
+	    pass
+
+	# Try VUNIT_GHDL_PATH (path of the ghdl binary when using VUnit).
+	r = os.environ.get("VUNIT_GHDL_PATH")
+	try:
+	  return _check_libghdl_bindir(Path(r), basename)
+	except (TypeError, FileNotFoundError):
+	    pass
+
+	# Try GHDL (name/path of the ghdl binary)
+	r = os.environ.get("GHDL", "ghdl")
+	r = which(r)
+	try:
+	    return _check_libghdl_bindir(Path(r).parent, basename)
+	except (TypeError, FileNotFoundError):
+	    pass
+
+	# Try within libghdl/ python installation
+	r = Path(__file__)
+	try:
+	    return _check_libghdl_bindir(r.parent, basename)
+	except (TypeError, FileNotFoundError):
+	    pass
+
+	# Try when running from the build directory
+	r = (r.parent / "../../lib").resolve()
+	try:
+	    return _check_libghdl_libdir(r, basename)
+	except (TypeError, FileNotFoundError):
+	    pass
+
+	# Failed.
+	raise Exception("Cannot find libghdl {}".format(basename))
 
 def _initialize():
-    # Load the shared library
-    _libghdl_path = _get_libghdl_path()
-    # print("Load {}".format(_libghdl_path))
-    libghdl = CDLL(str(_libghdl_path))
+	# Load the shared library
+	_libghdl_path = _get_libghdl_path()
+	# print("Load {}".format(_libghdl_path))
+	libghdl = CDLL(str(_libghdl_path))
 
-    # Initialize it.
-    # First Ada elaboration (must be the first call)
-    libghdl.libghdl_init()
-    # Then 'normal' initialization (set hooks)
-    libghdl.libghdl__set_hooks_for_analysis()
+	# Initialize it.
+	# First Ada elaboration (must be the first call)
+	libghdl.libghdl_init()
+	# Then 'normal' initialization (set hooks)
+	libghdl.libghdl__set_hooks_for_analysis()
 
-    # Set the prefix in order to locate the VHDL libraries.
-    prefix = str(_libghdl_path.parent.parent).encode("utf-8")
-    libghdl.libghdl__set_exec_prefix(c_char_p(prefix), len(prefix))
+	# Set the prefix in order to locate the VHDL libraries.
+	prefix = str(_libghdl_path.parent.parent).encode("utf-8")
+	libghdl.libghdl__set_exec_prefix(c_char_p(prefix), len(prefix))
 
-    return libghdl
+	return libghdl
 
 # Initialize shared library when package is loaded
 libghdl = _initialize()
@@ -150,48 +150,62 @@ libghdl = _initialize()
 
 @export
 def finalize() -> None:
-    """Free all the memory, be ready for a new initialization."""
-    libghdl.options__finalize()
+	"""Free all the memory, be ready for a new initialization."""
+	libghdl.options__finalize()
 
 
 @export
 def initialize() -> None:
-    """Initialize or re-initialize the shared library."""
-    libghdl.options__initialize()
+	"""Initialize or re-initialize the shared library."""
+	libghdl.options__initialize()
 
 
 @export
-def set_option(opt: str) -> bool:
-    """Set option :obj:`opt`. Return true, if the option is known and handled."""
-    opt = opt.encode("utf-8")
-    return libghdl.libghdl__set_option(c_char_p(opt), len(opt)) == 0
+def set_option(Opt: str) -> bool:
+	"""
+	Set option :obj:`opt`.
+
+	:param Opt: Option to set.
+	:return:    Return ``True``, if the option is known and handled.
+	"""
+	Opt = Opt.encode("utf-8")
+	return libghdl.libghdl__set_option(c_char_p(Opt), len(Opt)) == 0
 
 
 @export
 def analyze_init() -> None:
-    """
-    Initialize the analyzer.
+	"""
+	Initialize the analyzer.
 
-    .. deprecated:: 1.0.0
-       Deprecated as it may raise an exception. Use :func:`analyze_init_status`.
-    """
-    libghdl.libghdl__analyze_init()
+	.. deprecated:: 1.0.0
+	   Deprecated as it may raise an exception. Use :func:`analyze_init_status`.
+	"""
+	libghdl.libghdl__analyze_init()
 
 
 @export
 def analyze_init_status() -> int:
-    """Initialize the analyzer. Returns 0 in case of success."""
-    return libghdl.libghdl__analyze_init_status()
+	"""
+	Initialize the analyzer.
+
+	:return: Returns 0 in case of success.
+	"""
+	return libghdl.libghdl__analyze_init_status()
 
 
 @export
 def analyze_file(fname: str) -> Iir:
-    """Analyze a given filename :obj:`fname`."""
-    fname = fname.encode("utf-8")
-    return libghdl.libghdl__analyze_file(c_char_p(fname), len(fname))
+	"""
+	Analyze a given filename :obj:`fname`.
+
+	:param fname: File name
+	:return:      Internal Intermediate Representation (IIR)
+	"""
+	fname = fname.encode("utf-8")
+	return libghdl.libghdl__analyze_file(c_char_p(fname), len(fname))
 
 
 @export
 def disp_config() -> None:
-    """Display the configured prefixes for libghdl."""
-    libghdl.ghdllocal__disp_config_prefixes()
+	"""Display the configured prefixes for libghdl."""
+	libghdl.ghdllocal__disp_config_prefixes()
diff --git a/pyGHDL/libghdl/files_map.py b/pyGHDL/libghdl/files_map.py
index 423cec480..ba937a776 100644
--- a/pyGHDL/libghdl/files_map.py
+++ b/pyGHDL/libghdl/files_map.py
@@ -242,9 +242,9 @@ def Discard_Source_File(File: SourceFileEntry) -> None:
 	"""
 	Mark :obj:`File` as unavailable: clear the name and directory.
 
-  .. hint:: This is needed before creating a new source file with the same name.
+	.. hint:: This is needed before creating a new source file with the same name.
 
-  :param File: Source file to discard.
+	:param File: Source file to discard.
 	"""
 	libghdl.files_map__discard_source_file(File)