Enhanced docstrings for Python/Ada interface.

1 files changed, 106 insertions, 22 deletions

diff --git a/pyGHDL/libghdl/vhdl/lists.py b/pyGHDL/libghdl/vhdl/lists.py
index efb5b4ea9..dc4391ebf 100644
--- a/pyGHDL/libghdl/vhdl/lists.py
+++ b/pyGHDL/libghdl/vhdl/lists.py
@@ -7,12 +7,13 @@
 # |_|    |___/                                     |___/
 # =============================================================================
 # Authors:          Tristan Gingold
+#                   Patrick Lehmann
 #
-# Package package:  Python binding and low-level API for shared library 'libghdl'.
+# Package module:   Python binding and low-level API for shared library 'libghdl'.
 #
 # License:
 # ============================================================================
-# Copyright (C) 2019-2020 Tristan Gingold
+# Copyright (C) 2019-2021 Tristan Gingold
 #
 #	GHDL is free software; you can redistribute it and/or modify it under
 #	the terms of the GNU General Public License as published by the Free
@@ -39,34 +40,117 @@ from pydecor import export
 from pyGHDL.libghdl import libghdl
 
 
-List_Type = c_int32
+@export
+class Iterator(Structure):
+	_fields_ = [
+		("chunk", c_int32),
+		("chunk_idx", c_int32),
+		("remain", c_int32)
+	]
 
 
 @export
-class Iterator(Structure):
-    _fields_ = [("chunk", c_int32), ("chunk_idx", c_int32), ("remain", c_int32)]
+def Iterate(List) -> Iterator:
+	"""
+	Create an iterator for a given list.
+
+	The idiomatic way to iterate is:
 
+	.. code-block:: Python
 
-Iterate = libghdl.vhdl__lists__iterate
-Iterate.argstype = [List_Type]
-Iterate.restype = Iterator
+	   It = Iterate(List)
+	   while Is_Valid(It):
+	     El = Get_Element(It)
+	       # ...
+	     Next(It)
 
-Is_Valid = libghdl.vhdl__lists__is_valid
-Is_Valid.argstype = [POINTER(Iterator)]
-Is_Valid.restype = c_bool
+	:param List: List to create an iterator from.
+	:return:     Iterator structure.
+	"""
+	func = libghdl.vhdl__lists__iterate
+	func.argstype = [(c_int32)]
+	func.restype = Iterator
+
+	return func(List)
+
+
+@export
+def Is_Valid(Iterator) -> bool:
+	"""
+	Check if iterator reached the end.
 
-Next = libghdl.vhdl__lists__next
-Next.argstype = [POINTER(Iterator)]
-Next.restype = None
+	:param Iterator: Iterator to check.
+	:return:         False, if iterator has reached the end.
+	"""
+	func = libghdl.vhdl__lists__is_valid
+	func.argstype = [POINTER(Iterator)]
+	func.restype = c_bool
 
-Get_Element = libghdl.vhdl__lists__get_element
-Get_Element.argstype = [POINTER(Iterator)]
-Get_Element.restype = c_int32
+	return func(Iterator)
 
-Get_Nbr_Elements = libghdl.vhdl__lists__get_nbr_elements
-Get_Nbr_Elements.argtype = [List_Type]
-Get_Nbr_Elements.restype = c_int32
 
-Create_Iir_List = libghdl.vhdl__lists__create_list
+@export
+def Next(Iterator):
+	"""
+	Move iterator to the next element.
+
+	:param Iterator: Iterator to increment.
+	:return:         False, if iterator has reached the end.
+	"""
+	func = libghdl.vhdl__lists__next
+	func.argstype = [POINTER(Iterator)]
+	func.restype = None
+
+	func(Iterator)
+
+
+@export
+def Get_Element(Iterator) -> int:
+	"""
+	Get the current element from iterator.
+
+	:param Iterator: Iterator the get the element from.
+	:return:         The current element the iterator points to. Type: ``El_Type``
+	"""
+	func = libghdl.vhdl__lists__get_element
+	func.argstype = [POINTER(Iterator)]
+	func.restype = c_int32
+
+	return func(Iterator)
+
+
+@export
+def Get_Nbr_Elements(List) -> int:
+	"""
+	Return the number of elements in the list.
+
+	.. hint:: This is also 1 + the position of the last element.
+
+	:param List: The list to use.
+	:return:     Number of list elements.
+	"""
+	func = libghdl.vhdl__lists__get_nbr_elements
+	func.argtype = [(c_int32)]
+	func.restype = c_int32
+
+	return func(List)
+
+
+@export
+def Create_Iir_List():
+	"""
+	Create a list.
+
+	:return: Type: ``List_Type``
+	"""
+	return libghdl.vhdl__lists__create_list()
+
+
+@export
+def Destroy_Iir_List(List) -> None:
+	"""
+	Destroy a list.
 
-Destroy_Iir_List = libghdl.vhdl__lists__destroy_list
+	:param List: List to destroy.
+	"""
+	libghdl.vhdl__lists__destroy_list(List)