Even more doc-strings.

pyVHDLModel/Base.py

@@ -107,7 +107,7 @@ class ModelEntity(metaclass=ExtendedType, slots=True):
 	available and a readonly property :attr:`Parent`.
 	"""
 
-	_parent: 'ModelEntity'      #: Reference to a parent entity in the model.
+	_parent: 'ModelEntity'      #: Reference to a parent entity in the logical model hierarchy.
 
 	def __init__(self, parent: Nullable["ModelEntity"] = None) -> None:
 		"""
@@ -120,9 +120,9 @@ def __init__(self, parent: Nullable["ModelEntity"] = None) -> None:
 	@readonly
 	def Parent(self) -> 'ModelEntity':
 		"""
-		Returns a reference to the parent entity.
+		Read-only property to access the model entity's parent element reference in a logical hierarchy (:attr:`_parent`).
 
-		:returns: Parent entity.
+		:returns: Reference to the parent entity.
 		"""
 		return self._parent
 
@@ -285,23 +285,35 @@ def Documentation(self) -> Nullable[str]:
 
 @export
 class ConditionalMixin(metaclass=ExtendedType, mixin=True):
-	"""A ``BaseConditional`` is a mixin-class for all statements with a condition."""
+	"""A ``ConditionalMixin`` is a mixin-class for all statements with a condition."""
 
 	_condition: ExpressionUnion
 
 	def __init__(self, condition: Nullable[ExpressionUnion] = None) -> None:
+		"""
+		Initializes a statement with a condition.
+
+		When the condition is not None, the condition's parent reference is set to this statement.
+
+		:param condition: The expression representing the condition.
+		"""
 		self._condition = condition
 		if condition is not None:
 			condition._parent = self
 
-	@property
+	@readonly
 	def Condition(self) -> ExpressionUnion:
+		"""
+		Read-only property to access the condition of a statement (:attr:`_condition`).
+
+		:returns: The expression representing the condition of a statement.
+		"""
 		return self._condition
 
 
 @export
 class BranchMixin(metaclass=ExtendedType, mixin=True):
-	"""A ``BaseBranch`` is a mixin-class for all statements with branches."""
+	"""A ``BranchMixin`` is a mixin-class for all statements with branches."""
 
 	def __init__(self) -> None:
 		pass

pyVHDLModel/DesignUnit.py

@@ -274,10 +274,24 @@ def ReferencedContexts(self) -> Dict[str, 'Context']:
 
 	@property
 	def DependencyVertex(self) -> Vertex:
+		"""
+		Read-only property to access the corresponding dependency vertex (:attr:`_dependencyVertex`).
+
+		The dependency vertex references this design unit by its value field.
+
+		:returns: The corresponding dependency vertex.
+		"""
 		return self._dependencyVertex
 
 	@property
 	def HierarchyVertex(self) -> Vertex:
+		"""
+		Read-only property to access the corresponding hierarchy vertex (:attr:`_hierarchyVertex`).
+
+		The hierarchy vertex references this design unit by its value field.
+
+		:returns: The corresponding hierarchy vertex.
+		"""
 		return self._hierarchyVertex
 
 
@@ -394,6 +408,8 @@ class Package(PrimaryUnit, DesignUnitWithContextMixin, ConcurrentDeclarationRegi
 	      end package;
 	"""
 
+	_packageBody:       Nullable["PackageBody"]
+
 	_genericItems:      List[GenericInterfaceItemMixin]
 
 	_deferredConstants: Dict[str, DeferredConstant]
@@ -412,6 +428,8 @@ def __init__(
 		DesignUnitWithContextMixin.__init__(self)
 		ConcurrentDeclarationRegionMixin.__init__(self, declaredItems)
 
+		self._packageBody = None
+
 		# TODO: extract to mixin
 		self._genericItems = []  # TODO: convert to dict
 		if genericItems is not None:
@@ -422,6 +440,10 @@ def __init__(
 		self._deferredConstants = {}
 		self._components = {}
 
+	@property
+	def PackageBody(self) -> Nullable["PackageBody"]:
+		return self._packageBody
+
 	@property
 	def GenericItems(self) -> List[GenericInterfaceItemMixin]:
 		return self._genericItems

pyVHDLModel/Object.py

@@ -78,6 +78,13 @@ def Subtype(self) -> Symbol:
 
 	@readonly
 	def ObjectVertex(self) -> Nullable[Vertex]:
+		"""
+		Read-only property to access the corresponding object vertex (:attr:`_objectVertex`).
+
+		The object vertex references this Object by its value field.
+
+		:returns: The corresponding object vertex.
+		"""
 		return self._objectVertex
 
 

pyVHDLModel/Regions.py

@@ -46,20 +46,21 @@
 
 @export
 class ConcurrentDeclarationRegionMixin(metaclass=ExtendedType, mixin=True):
-	_declaredItems:   List  # FIXME: define list prefix type e.g. via Union
+	# FIXME: define list prefix type e.g. via Union
+	_declaredItems:   List                              #: List of all declared items in this concurrent declaration region.
 
 	# _attributes:     Dict[str, Attribute]
 	# _aliases:        Dict[str, Alias]
-	_types:           Dict[str, FullType]
-	_subtypes:        Dict[str, Subtype]
+	_types:           Dict[str, FullType]               #: Dictionary of all types declared in this concurrent declaration region.
+	_subtypes:        Dict[str, Subtype]                #: Dictionary of all subtypes declared in this concurrent declaration region.
 	# _objects:        Dict[str, Union[Constant, Variable, Signal]]
-	_constants:       Dict[str, Constant]
-	_signals:         Dict[str, Signal]
-	_sharedVariables: Dict[str, SharedVariable]
-	_files:           Dict[str, File]
-	_subprograms:     Dict[str, Dict[str, Subprogram]]
-	_functions:       Dict[str, Dict[str, Function]]
-	_procedures:      Dict[str, Dict[str, Procedure]]
+	_constants:       Dict[str, Constant]               #: Dictionary of all constants declared in this concurrent declaration region.
+	_signals:         Dict[str, Signal]                 #: Dictionary of all signals declared in this concurrent declaration region.
+	_sharedVariables: Dict[str, SharedVariable]         #: Dictionary of all shared variables declared in this concurrent declaration region.
+	_files:           Dict[str, File]                   #: Dictionary of all files declared in this concurrent declaration region.
+	# _subprograms:     Dict[str, Dict[str, Subprogram]]  #: Dictionary of all subprograms declared in this concurrent declaration region.
+	_functions:       Dict[str, Dict[str, Function]]    #: Dictionary of all functions declared in this concurrent declaration region.
+	_procedures:      Dict[str, Dict[str, Procedure]]   #: Dictionary of all procedures declared in this concurrent declaration region.
 
 	def __init__(self, declaredItems: Nullable[Iterable] = None) -> None:
 		# TODO: extract to mixin
@@ -76,7 +77,7 @@ def __init__(self, declaredItems: Nullable[Iterable] = None) -> None:
 		self._signals =     {}
 		self._sharedVariables = {}
 		self._files =       {}
-		self._subprograms = {}
+		# self._subprograms = {}
 		self._functions =   {}
 		self._procedures =  {}
 
@@ -112,9 +113,9 @@ def SharedVariables(self) -> Dict[str, SharedVariable]:
 	def Files(self) -> Dict[str, File]:
 		return self._files
 
-	@readonly
-	def Subprograms(self) -> Dict[str, Subprogram]:
-		return self._subprograms
+	# @readonly
+	# def Subprograms(self) -> Dict[str, Subprogram]:
+	# 	return self._subprograms
 
 	@readonly
 	def Functions(self) -> Dict[str, Dict[str, Function]]:
@@ -125,6 +126,35 @@ def Procedures(self) -> Dict[str, Dict[str, Procedure]]:
 		return self._procedures
 
 	def IndexDeclaredItems(self) -> None:
+		"""
+		Index declared items listed in the concurrent declaration region.
+
+		.. rubric:: Algorithm
+
+		1. Iterate all declared items:
+
+		   * Every declared item is added to :attr:`_namespace`.
+		   * If the declared item is a :class:`~pyVHDLModel.Type.FullType`, then add an entry to :attr:`_types`.
+		   * If the declared item is a :class:`~pyVHDLModel.Type.SubType`, then add an entry to :attr:`_subtypes`.
+		   * If the declared item is a :class:`~pyVHDLModel.Subprogram.Function`, then add an entry to :attr:`_functions`.
+		   * If the declared item is a :class:`~pyVHDLModel.Subprogram.Procedure`, then add an entry to :attr:`_procedures`.
+		   * If the declared item is a :class:`~pyVHDLModel.Object.Constant`, then add an entry to :attr:`_constants`.
+		   * If the declared item is a :class:`~pyVHDLModel.Object.Signal`, then add an entry to :attr:`_signals`.
+		   * If the declared item is a :class:`~pyVHDLModel.Object.Variable`, TODO.
+		   * If the declared item is a :class:`~pyVHDLModel.Object.SharedVariable`, then add an entry to :attr:`_sharedVariables`.
+		   * If the declared item is a :class:`~pyVHDLModel.Object.File`, then add an entry to :attr:`_files`.
+		   * If the declared item is neither of these types, call :meth:`_IndexOtherDeclaredItem`. |br|
+		     Derived classes may override this virtual function.
+
+		.. seealso::
+
+		   :meth:`pyVHDLModel.Design.IndexPackages`
+		     Iterate all packages in the design and index declared items.
+		   :meth:`pyVHDLModel.Library.IndexPackages`
+		     Iterate all packages in the library and index declared items.
+		   :meth:`pyVHDLModel.Library._IndexOtherDeclaredItem`
+		     Iterate all packages in the library and index declared items.
+		"""
 		for item in self._declaredItems:
 			if isinstance(item, FullType):
 				self._types[item._normalizedIdentifier] = item

pyVHDLModel/Sequential.py

@@ -66,6 +66,11 @@ def __init__(self, statements: Nullable[Iterable[SequentialStatement]] = None) -
 
 	@readonly
 	def Statements(self) -> List[SequentialStatement]:
+		"""
+		Read-only property to access the list of sequential statements (:attr:`_statements`).
+
+		:returns: A list of sequential statements.
+		"""
 		return self._statements
 
 
@@ -105,6 +110,11 @@ def __init__(self, target: Symbol, waveform: Iterable[WaveformElement], label: N
 
 	@readonly
 	def Waveform(self) -> List[WaveformElement]:
+		"""
+		Read-only property to access the list waveform elements (:attr:`_waveform`).
+
+		:returns: A list of waveform elements.
+		"""
 		return self._waveform
 
 
@@ -204,14 +214,29 @@ def __init__(
 
 	@readonly
 	def IfBranch(self) -> IfBranch:
+		"""
+		Read-only property to access the if-branch of the if-statement (:attr:`_ifBranch`).
+
+		:returns: The if-branch.
+		"""
 		return self._ifBranch
 
 	@property
 	def ElsIfBranches(self) -> List['ElsifBranch']:
+		"""
+		Read-only property to access the elsif-branch of the if-statement (:attr:`_elsifBranch`).
+
+		:returns: The elsif-branch.
+		"""
 		return self._elsifBranches
 
 	@property
 	def ElseBranch(self) -> Nullable[ElseBranch]:
+		"""
+		Read-only property to access the else-branch of the if-statement (:attr:`_elseBranch`).
+
+		:returns: The else-branch.
+		"""
 		return self._elseBranch