added documentation

scripts/Infrastructure/Template.py

@@ -68,13 +68,27 @@ class TemplateManager:
     Class Overview:
         The `TemplateManager` class is responsible for managing MPI error case templates.
 
+    Attributes:
+        _descr_full (str): The full description of the template.
+        _descr_short (str): The short description of the template.
+        _instructions (list): List of instruction blocks.
+        _thread_level (str): The MPI thread level to use.
+        _min_ranks (int): The minimum number of MPI ranks.
+        _has_finalize (bool): Whether to include a call to MPI_Finalize.
+        _has_init (bool): Whether to include a call to MPI_Init.
+
     Methods:
-            - `__init__(self)`: Initializes a new instance of the TemplateManager class.
-            - `__str__(self)`: Converts the TemplateManager instance to a string, replacing placeholders.
-            - `register_instruction_block(self, block)`: Registers an instruction block with the template.
-            - `get_version(self)`: Retrieves required MPI version.
-            - `set_description(self, descr_short, descr_full)`: Sets the short and full descriptions.
-            - `get_short_descr(self)`: Retrieves the short description .
+        - __init__(self, min_ranks: int = 2, thread_level: str = None, has_finalize: bool = True,
+                 has_init: bool = True): Initializes a new instance of the TemplateManager class.
+        - __str__(self): Converts the TemplateManager instance to a string, replacing placeholders.
+        - register_instruction(self, inst: Instruction | typing.List[Instruction]): Registers an instruction with the template.
+        - get_version(self) -> str: Retrieves the minimum required MPI version.
+        - set_description(self, descr_short: str, descr_full: str): Sets the short and full descriptions for the template.
+        - get_short_descr(self) -> str: Retrieves the short description (to use as a filename).
+        - get_instruction(self, identifier: str = None, return_list=False, idx: int = None) -> Instruction | typing.List[Instruction]: Retrieves an instruction or list of them based on its identifier or index.
+        - insert_instruction(self, new_instruction: Instruction, after_instruction: str | int = None, before_instruction: str | int = None): Inserts a new instruction into the template.
+        - remove_instruction(self, identifier: str = None, idx: int | typing.List[int] = None): Removes an instruction from the template.
+        - replace_instruction(self, new_instruction=Instruction, identifier: str = None, idx: int | typing.List[int] = None): Replaces an instruction in the template with a new one.
     """
 
     def __init__(self, min_ranks: int = 2, thread_level: str = None, has_finalize: bool = True, has_init: bool = True):
@@ -169,7 +183,18 @@ class TemplateManager:
     def get_instruction(self, identifier: str = None, return_list=False, idx: int = None) -> Instruction | typing.List[
         Instruction]:
         """
-        TODO DOCUMENTATION
+        Retrieves an instruction or list fh them  based on its identifier or index.
+
+        Parameters:
+            identifier (str): The identifier of the instruction.
+            return_list (bool): Whether to return a list of instruction.
+            idx (int): The index of the instruction block.
+
+        Returns:
+            Instruction | List[Instruction]: The instruction block(s).
+        Raises:
+            ValueError: if both index and identifier are provided
+            IndexError: if return_list is False and not exactely one instruction is found by index
         """
         # assert only one param is not None
         parameters = [identifier, idx]
@@ -196,14 +221,22 @@ class TemplateManager:
 
     def __get_instruction_index(self, identifier: str) -> typing.List[int]:
         """
-         TODO: documentation
+         internal helper function to receive the indices of instructions with ghe given identifier
          """
         return [idx for inst, idx in enumerate(self._instructions) if inst.get_identifier() == identifier]
 
     def insert_instruction(self, new_instruction: Instruction, after_instruction: str | int = None,
                            before_instruction: str | int = None):
         """
-         TODO: documentation
+        Inserts a new instruction into the template.
+
+        Parameters:
+            new_instruction (Instruction): The new instruction to insert.
+            after_instruction (str | int): The instruction after which to insert the new one (identifier or index).
+            before_instruction (str | int): The instruction before which to insert the new one (identifier or index).
+        Raises:
+            ValueError: if both before and after are provided
+            IndexError: if it finds multiple places to insert by identifier
         """
         # assert only one param is not None
         parameters = [after_instruction, before_instruction]
@@ -234,8 +267,13 @@ class TemplateManager:
 
     def remove_instruction(self, identifier: str = None, idx: int | typing.List[int] = None):
         """
-         TODO: documentation
+            Removes an instruction from the template.
+
+            Parameters:
+                identifier (str): The identifier of the instruction to remove.
+                idx (int | List[int]): The index or list of indices of the instruction(s) to remove.
         """
+
         # assert only one param is not None
         parameters = [identifier, idx]
         if parameters.count(None) != 1:
@@ -260,10 +298,20 @@ class TemplateManager:
     def replace_instruction(self, new_instruction=Instruction, identifier: str = None,
                             idx: int | typing.List[int] = None):
         """
-         TODO: documentation
+        Replaces an instruction in the template with a new one.
+
+        Parameters:
+            new_instruction (Instruction | List[Instruction]): The new instruction(s) to replace with.
+            identifier (str): The identifier of the instruction to replace.
+            idx (int | List[int]): The index or list of indices of the instruction(s) to replace.
+        Raises
+        ValueError: if the number of instructions to replace does not match the number of instructions provided
+                    or if both idx and identifier are provided
+        Notes: The instructions to be replaced must not be in contiguous order
         """
-        # assert only one param is not None
         parameters = [identifier, idx]
+        if parameters.count(None) != 1:
+            raise ValueError("Only one parameter is allowed to be specified")
 
         new_instruction_list = []
         if isinstance(new_instruction, Instruction):