Refactored docstrings of processor class

src/simudator/core/processor.py

@@ -116,34 +116,54 @@ class Processor:
 
         Each entry in the list is a tuple of a instruction with its column and
         row position for the pipeline diagram.
+
+        Returns
+        -------
+        list[tuple[str, int, int]]
+            A list of instructions represented as tuples. Each tuple contains
+            the instruction and its position in the pipeline.
         """
         raise NotImplementedError
 
     def get_pipeline_dimensions(self) -> tuple[int, int]:
-        """Return a tuple on the form (x, y) for the processors preferred
-        pipeline display size.
+        """Return the dimensions of the pipeline of the processor.
 
-        (x, y) represents the number of columns respective rows the pipeline
-        should have.
+        Returns
+        -------
+        width : int
+            The width of the pipeline (number of cycles to display at a time).
+        depth : int
+           Depth of the pipeline.
         """
         raise NotImplementedError
 
     def get_asm_instruction(self) -> str:
-        """
-        Return a string containing the 'code' for the current assembly
+        """Return a string containing the 'code' for the current assembly
         instruction.
 
         What 'code' refers to is up to each processor to define. It could be a
         memory address, an instruction label or something else.
+
+        Returns
+        -------
+        str
+            The current assembly instruction.
         """
         raise NotImplementedError
 
     def run_asm_instruction(self, num_instructions=1) -> None:
-        """
-        Runs assembler instructions on the processors 'num_instructions' times.
+        """Run a number of assembly instructions.
 
-        Default argument is one, but it is possible to specify any number of
-        instructions. This should be implemented per processor and thus we
+        Defaults to running 1 instruction unless some other number is provided.
+
+        Parameters
+        ----------
+        num_instructions : int
+            Number of assembly instructions to perform.
+
+        Notes
+        -----
+        This should be implemented per processor and thus we
         raise NotImplementedError.
         """
 
@@ -151,14 +171,15 @@ class Processor:
 
     def undo_asm_instruction(self, num_instructions=1) -> None:
         """
-        Undos 'num_instructions' numbers of assembler instructions on the CPU.
+        Undo a number of assembly instructions on the CPU.
 
         Default argument is one, but it is possible to specify any number of
-        instructions. Undo assembler instruction assumes the CPU is always at
-        the end of the list 'self.assembly_cycles'.
+        instructions.
 
-        Undos asm instructions by finding the corresponding clock cycle before
-        said number of asm instructions started and loading that clock cycle.
+        Parameters
+        ----------
+        num_instructions : int
+            Number of assembly instructions to undo.
         """
 
         current_clock_cycle = self.clock
@@ -196,7 +217,12 @@ class Processor:
 
     def should_halt(self) -> bool:
         """
-        Return True when the processor should halt, otherwise False.
+        Return whether the processor should halt this clock cycle or not.
+
+        Returns
+        -------
+        bool
+            ``True`` if the processor should halt, ``False`` otherwise.
 
         Notes
         ----
@@ -208,16 +234,13 @@ class Processor:
         return False
 
     def stop(self) -> None:
-        """
-        Signal to stop the execution of the processor until the processor is
+        """Signal to stop the execution of the processor until the processor is
         instructed to run continuously or do some ticks again.
         """
         self.is_stopped = True
 
     def unstop(self) -> None:
-        """
-        Reset the stop execution signal.
-        """
+        """Reset the stop execution signal."""
         self.is_stopped = False
 
     def is_new_instruction(self) -> bool:
@@ -267,45 +290,83 @@ class Processor:
             module.update_logic()
 
     def add_modules_to_update(self, module: Module) -> None:
-        """
-        Queues module to be updated at the end of clock cycle.
+        """Queue a module to be updated at the end of clock cycle.
+
+        Parameters
+        ----------
+        module : Module
+            Module to queue for update.
+
+        See Also
+        --------
+        Module.update_logic :
+            Method for updating a module.
         """
         if module not in self.update_queue:
             self.update_queue.append(module)
 
     def add_module(self, module: Module) -> None:
-        """
-        Add module into the processor.
+        """Add module to be simulated by the processor.
+
+        Parameters
+        ----------
+        module : Module
+            Module to add.
         """
         self.modules[module.name] = module
 
     def get_module(self, name: str) -> Module:
-        """
-        Get module with specific name.
+        """Get module with specific name.
+
+        Parameters
+        ----------
+        name : str
+            Name of the module to get.
+
+        Returns
+        -------
+        Module
+            The module with the specified name.
         """
         return self.modules[name]
 
     def get_modules(self) -> list[Module]:
-        """
-        Get list of all modules.
+        """Get list of all modules.
+
+        Returns
+        -------
+        list[Module]
+            List of all modules in the processor.
         """
         return list(self.modules.values())
 
     def add_signals(self, signals: list[Signal]) -> None:
-        """
-        Add signals into the processor.
+        """Add signals to the processor.
+
+        Parameters
+        ----------
+        list[Signal]
+            List of signals to add for simulation.
         """
         self.signals += signals
 
     def get_clock(self) -> int:
-        """
-        Get current clockcycle.
+        """Get the current clockcycle number.
+
+        Returns
+        -------
+        int
+            Current clock cycle number of the processor.
         """
         return self.clock
 
     def set_clock(self, value: int) -> None:
-        """
-        Set current clockcycle.
+        """Set current clockcycle number.
+
+        Parameters
+        ----------
+        value : int
+            Cycle number to set the clock to.
         """
         self.clock = value
 
@@ -327,10 +388,15 @@ class Processor:
         self.module_history.append(module_states)
 
     def load_cycle(self, cycle: int) -> None:
-        """
-        Load the state of all modules as they were at the specified clock cycle.
+        """Load the state of all modules as they were at the specified clock
+        cycle.
 
         This does not erase the history of states for the later cycles.
+
+        Parameters
+        ----------
+        cycle : int
+            Number of the cycle to load.
         """
 
         cycle_index = cycle - self.removed_cycles
@@ -355,13 +421,13 @@ class Processor:
             module = self.update_queue.pop(0)
             module.update_logic()
 
-    def load_state_from_file(self, file_path) -> None:
-        """
-        Loads states for modules from a file.
+    def load_state_from_file(self, file_path: str) -> None:
+        """Load states for modules from a file.
 
-        Appends the lines from the loaded file to a long string. This string
-        is given to each module in the function 'load_from_str'. Each module
-        will thus load itself.
+        Parameters
+        ----------
+        file_path : str
+            Path to the file containing the processor state to load.
         """
         self.reset()
 
@@ -374,6 +440,9 @@ class Processor:
         else:
             raise ValueError  # Else raise error
 
+        # Appends the lines from the loaded file to a long string. This string
+        # is given to each module in the function 'load_from_str'. Each module
+        # will thus load itself.
         module_name = None
         module_str = ""
 
@@ -405,10 +474,14 @@ class Processor:
             module.load_from_str(module_str)
 
     def save_state_to_file(self, file_path: str) -> None:
-        """
-        Saves the current state of the cpu to a given file.
+        """Save the current state of the cpu to file.
 
         Will overwrite the given file.
+
+        Parameters
+        ----------
+        file_path : str
+            Path to the file to write to.
         """
         file = open(file_path, "w")
         file.write("")
@@ -419,13 +492,21 @@ class Processor:
             module.save_state_to_file(file_path)
 
     def pretty_print(self) -> None:
+        """Print the processor state in a readable and compact format."""
         self.pretty_print_verbose(self.ignore_keys)
 
     def pretty_print_verbose(self, ignore_keys=None) -> None:
         """
-        Prints the most relevant information about each module
-        compact and pretty. Fields of modules can be ignored with the
-        optional argument 'ignore_keys'.
+        Print the most relevant information about each module in a compact and
+        readable format.
+
+        State variables of modules can be ignored with the optional argument.
+
+        Parameters
+        ----------
+        ignore_keys : list[str]
+            List of names of state variables of modules to exclude when
+            printing module states.
         """
         # TODO: ignore keys per module and not for all modules
         memory_modules = []
@@ -455,7 +536,8 @@ class Processor:
         module_to_line_length = {}
         # get the longest line length for all other_modules
         for module in other_modules:
-            line_len = module.get_longest_line_len(ignore_keys) + 3  # +3 for padding
+            # +3 for padding
+            line_len = module.get_longest_line_len(ignore_keys) + 3
 
             # TODO: what to do if two or more modules has the same name
             module_to_line_length[module] = line_len
@@ -464,7 +546,7 @@ class Processor:
 
         print(Processor.LINE_SEPARATOR * Processor.MAX_LINE_LEN)
 
-        # print each group seperate
+        # print each group separate
         for group in groups:
             self.pretty_print_names(group)
 
@@ -493,8 +575,7 @@ class Processor:
                             real_keys[row] + ": " + str(module_state[real_keys[row]])
                         )
 
-                    # padd the string so each string has the same
-                    # length
+                    # pad the string so each string has the same length
                     total_padding += module_to_line_length[module]
                     string = string.ljust(total_padding)
                     # replace last to chars with a separator and padding
@@ -506,7 +587,14 @@ class Processor:
         for memory_module in memory_modules:
             self.pretty_print_memory(memory_module)
 
-    def pretty_print_memory(self, module: Module) -> None:
+    def pretty_print_memory(self, module: Memory) -> None:
+        """Print a memory module in a compact and readable format.
+
+        Parameters
+        ----------
+        module : Memory
+            Memory module to print the state of.
+        """
         print(module.name)
         print(Processor.LINE_SEPARATOR * Processor.MAX_LINE_LEN)
 
@@ -515,11 +603,11 @@ class Processor:
         string = ""
         last_mem_len = module.get_largest_mem_adr()
 
-        for i, value in enumerate(module.memory):
+        for i, value in enumerate(module.get_state()["memory"]):
 
-            # create a new string containg the adress and the value
-            # of the memory adress formattet to fit with the largest
-            # adress and largest memory value
+            # create a new string containing the address and the value
+            # of the memory address formatted to fit with the largest
+            # address and largest memory value
             new_row = (str(i).ljust(last_mem_len) + ": " + str(value)).ljust(
                 longest_line_len + last_mem_len + 3
             ) + "|"
@@ -542,11 +630,16 @@ class Processor:
 
     def pretty_print_names(self, module_to_line_length: dict[Module, int]) -> None:
         """
-        Prints the name of the modules in one row, but pretty.
+        Print the name of the modules in one row with formatting.
 
+        Adds spacing between the names so that the longest state variable of
+        each module has space to be printed below the name.
 
-        Adds spacing between the names so that the modules
-        longest field will have space to be printed below.
+        Parameters
+        ----------
+        module_to_line_length : dict[Module, int]
+            Mapping from module to length of the longest state variable of
+            the module.
         """
         name_string = ""
         total_len = 0
@@ -561,9 +654,20 @@ class Processor:
     def group_pp_modules(
         self, module_to_line_length: dict[Module, int]
     ) -> list[dict[Module, int]]:
-        """
-        Groups the modules to be pretty printed into groups with a
+        """Group the modules to be pretty printed into groups with a
         total line length lower than 'Processor.MAX_LINE_LEN'.
+
+        Parameters
+        ----------
+        module_to_line_length : dict[Module, int]
+            Mapping from module to length of the longest state variable of
+            the module (takes as the line length).
+
+        Returns
+        -------
+        list[dict[Module, int]]
+            List of mappings from module to line length, each mapping
+            representing a group of modules for printing.
         """
 
         groups = [{}]
@@ -586,8 +690,21 @@ class Processor:
 
     def fields_to_list(self, module: Module, ignore_keys=[]) -> list[str]:
         """
-        Return a list containing all the keys for a module except the name.
-        Optinal argument to ignore specific keys.
+        Return a list containing all state variable names, excluding module
+        name, for a module.
+        Optional argument to ignore specific state variables.
+
+        Parameters
+        ----------
+        module : Module
+            Module to get state variable names from.
+        ignore_keys : list[str]
+            List of state variable names to exclude.
+
+        Returns
+        -------
+        list[str]
+            List of state variable names, excluding module name, of a module.
         """
         return [
             key
@@ -595,11 +712,24 @@ class Processor:
             if key != "name" and key not in ignore_keys
         ]
 
-    def get_most_fields(self, modules: dict[Module,int], ignore_keys=[]) -> int:
-        """
-        Return the most number of a fields a module has.
+    def get_most_fields(self, modules: dict[Module, int], ignore_keys=[]) -> int:
+        """Get the maximum number of state variables among all modules.
 
         Can optionally ignore keys.
+
+        Parameters
+        ----------
+        modules : dict[Module, int]
+            Mapping from module to length of the longest state variable of
+            the module. Used as a list of modules to take the maximum over.
+        ignore_keys : list[str]
+            State variables to exclude.
+
+        Returns
+        -------
+        int
+            The maximum of the number of module state variables among all
+            modules of the processor.
         """
         fields = 0
         for module in modules:
@@ -612,6 +742,24 @@ class Processor:
     def add_state_breakpoint(
         self, module_name: str, state_name: str, value: Any
     ) -> None:
+        """Add a module state breakpoint to the processor.
+
+        Parameters
+        ----------
+            module_name : str
+                Name of the module for which a breakpoint will be added.
+            state_name : str
+                Name of the state variable of the module to put a breakpoint
+                on.
+            value : Any
+                Value of the state variable that triggers the breakpoint.
+
+        Raises
+        ------
+        ValueError
+            If the module does not exist or if the state variable does not
+            exist in the module.
+        """
 
         if module_name not in self.modules:
             raise ValueError(f"No module named {module_name}")
@@ -626,19 +774,43 @@ class Processor:
         self.breakpoint_id_counter += 1
 
     def remove_breakpoint(self, id: int) -> bool:
+        """Remove a specific breakpoint.
+
+        Parameters
+        ----------
+        id : int
+            ID of the breakpoint to be removed.
+        """
         if id in self.breakpoints:
             del self.breakpoints[id]
             return True
         return False
 
     def print_breakpoints(self) -> None:
+        """Print all breakpoints of the processor."""
         if not self.breakpoints:
             print("There are no breakpoints.")
         else:
             for bp_id, bp in self.breakpoints.items():
                 print(f"BP {bp_id}: {bp}")
 
-    def add_memory_breakpoint(self, module_name: str, adress: int, value: Any) -> None:
+    def add_memory_breakpoint(self, module_name: str, address: int, value: Any) -> None:
+        """Add a breakpoint for a memory module.
+
+        Parameters
+        ----------
+        module_name : str
+            Name of the memory module for which a breakpoint will be added.
+        address : int
+            Address of the memory module to break at.
+        value : Any
+            Value of the address that triggers the breakpoint.
+
+        Raises
+        ------
+        ValueError
+            If the module does not exist or is not a memory.
+        """
 
         if module_name not in self.modules:
             raise ValueError(f"No module named {module_name}")
@@ -647,14 +819,42 @@ class Processor:
         if "memory" not in module.get_state():
             raise ValueError(f"Module {module_name} is not a memory.")
 
-        bp = MemoryBreakpoint(module, adress, value)
+        bp = MemoryBreakpoint(module, address, value)
         self.breakpoints[self.breakpoint_id_counter] = bp
         self.breakpoint_id_counter += 1
 
     def get_breakpoint_lambdas(self) -> list[str]:
+        """Get all functions available for lambda breakpoints.
+
+        Returns
+        -------
+        list[str]
+            List of names of all functions of the processor that are available
+            for adding lambda breakpoints.
+        """
+
         return list(self.lambdas.keys())
 
     def add_lambda_breakpoint(self, lambda_name: str, **kwargs) -> None:
+        """Add a lambda breakpoint to the processor.
+
+        Module names used in the keyword arguments are substituted by the
+        actual modules before being passed on to the lambda breakpoint
+        function.
+
+        Parameters
+        ----------
+        lambda_name : str
+            Name of the lambda breakpoint function to be used by the
+            breakpoint.
+        **kwargs
+            Arguments to pass to the breakpoint function.
+
+        Raises
+        ------
+        ValueError
+            If the  lambda breakpoint function does not exist.
+        """
         # Substitute any module names for the module instances
         # This is to be able to externally create general lambda breakpoints
         # that can take any values as arguments while also having a way to take
@@ -673,4 +873,13 @@ class Processor:
         self.breakpoint_id_counter += 1
 
     def set_enabled_breakpoint(self, bp_id: int, is_enabled: bool) -> None:
+        """Toggle a breakpoint to enabled or disabled.
+
+        Parameters
+        ----------
+        bp_id : int
+            ID of the breakpoint to toggle.
+        is_enabled : bool
+            ``True`` to enable, ``False`` to disable the breakpoint.
+        """
         self.breakpoints[bp_id].set_enabled(is_enabled)