Transforming to Doxy style

Author: joserochh

assembler_tools/hec-assembler-tools/he_link.py

@@ -1,26 +1,11 @@
 #! /usr/bin/env python3
 # encoding: utf-8
 """
-This module provides functionality for linking assembled kernels into a full HERACLES program for execution queues: MINST, CINST, and XINST.
-
-Classes:
-    LinkerRunConfig
-        Maintains the configuration data for the run.
-
-    KernelFiles
-        Structure for kernel files.
-
-Functions:
-    main(run_config: LinkerRunConfig, verbose_stream=None)
-        Executes the linking process using the provided configuration.
-
-    parse_args() -> argparse.Namespace
-        Parses command-line arguments for the linker script.
-
-Usage:
-    This script is intended to be run as a standalone program. It requires specific command-line arguments
-    to specify input and output files and configuration options for the linking process.
+@file
+@brief This module provides functionality for linking assembled kernels into a full HERACLES program for execution queues: MINST, CINST, and XINST.
 
+This script is intended to be run as a standalone program. It requires specific command-line arguments
+to specify input and output files and configuration options for the linking process.
 """
 import argparse
 import io
@@ -48,11 +33,7 @@
 
 class LinkerRunConfig(RunConfig):
     """
-    Maintains the configuration data for the run.
-
-    Methods:
-        as_dict() -> dict
-            Returns the configuration as a dictionary.
+    @brief Maintains the configuration data for the run.
     """
 
     __initialized = False # specifies whether static members have been initialized
@@ -62,34 +43,27 @@ class LinkerRunConfig(RunConfig):
 
     def __init__(self, **kwargs):
         """
-        Constructs a new LinkerRunConfig Object from input parameters.
+        @brief Constructs a new LinkerRunConfig Object from input parameters.
 
         See base class constructor for more parameters.
 
-        Args:
-            input_prefixes (list[str]):
-                List of input prefixes, including full path. For an input prefix, linker will
+        @param kwargs Dictionary of configuration parameters:
+          - input_prefixes: List of input prefixes, including full path. For an input prefix, linker will
                 assume there are three files named `input_prefixes[i] + '.minst'`,
                 `input_prefixes[i] + '.cinst'`, and `input_prefixes[i] + '.xinst'`.
                 This list must not be empty.
-            output_prefix (str):
-                Prefix for the output file names.
+          - output_prefix: Prefix for the output file names.
                 Three files will be generated:
                 `output_dir/output_prefix.minst`, `output_dir/output_prefix.cinst`, and
                 `output_dir/output_prefix.xinst`.
                 Output filenames cannot match input file names.
-            input_mem_file (str):
-                Input memory file associated with the result kernel.
-            output_dir (str): current working directory
-                OPTIONAL directory where to store all intermediate files and final output.
+          - input_mem_file: Input memory file associated with the result kernel.
+          - output_dir: OPTIONAL directory where to store all intermediate files and final output.
                 This will be created if it doesn't exists.
                 Defaults to current working directory.
 
-        Raises:
-            TypeError:
-                A mandatory configuration value was missing.
-            ValueError:
-                At least, one of the arguments passed is invalid.
+        @throws TypeError A mandatory configuration value was missing.
+        @throws ValueError At least, one of the arguments passed is invalid.
         """
 
         self.init_default_config()
@@ -113,7 +87,7 @@ def __init__(self, **kwargs):
     @classmethod
     def init_default_config(cls):
         """
-        Initializes static members of the class.
+        @brief Initializes static members of the class.
         """
         if not cls.__initialized:
             cls.__default_config["input_prefixes"]  = None
@@ -129,10 +103,9 @@ def init_default_config(cls):
 
     def __str__(self):
         """
-        Provides a string representation of the configuration.
+        @brief Provides a string representation of the configuration.
     
-        Returns:
-            str: The string for the configuration.
+        @return The string for the configuration.
         """
         self_dict = self.as_dict()
         with io.StringIO() as retval_f:
@@ -143,10 +116,9 @@ def __str__(self):
 
     def as_dict(self) -> dict:
         """
-        Provides the configuration as a dictionary.
+        @brief Provides the configuration as a dictionary.
 
-        Returns:
-            dict: The configuration.
+        @return The configuration.
         """
         retval = super().as_dict()
         tmp_self_dict = vars(self)
@@ -155,17 +127,12 @@ def as_dict(self) -> dict:
 
 class KernelFiles(NamedTuple):
     """
-    Structure for kernel files.
-
-    Attributes:
-        minst (str):
-            Index = 0. Name for file containing MInstructions for represented kernel.
-        cinst (str):
-            Index = 1. Name for file containing CInstructions for represented kernel.
-        xinst (str):
-            Index = 2. Name for file containing XInstructions for represented kernel.
-        prefix (str):
-            Index = 3
+    @brief Structure for kernel files.
+
+    @var minst Index = 0. Name for file containing MInstructions for represented kernel.
+    @var cinst Index = 1. Name for file containing CInstructions for represented kernel.
+    @var xinst Index = 2. Name for file containing XInstructions for represented kernel.
+    @var prefix Index = 3
     """
     minst: str
     cinst: str
@@ -174,17 +141,14 @@ class KernelFiles(NamedTuple):
 
 def main(run_config: LinkerRunConfig, verbose_stream = None):
     """
-    Executes the linking process using the provided configuration.
+    @brief Executes the linking process using the provided configuration.
 
     This function prepares input and output file names, initializes the memory model, discovers variables,
     and links each kernel, writing the output to specified files.
 
-    Args:
-        run_config (LinkerRunConfig): The configuration object containing run parameters.
-        verbose_stream: The stream to which verbose output is printed. Defaults to None.
-
-    Returns:
-        None
+    @param run_config The configuration object containing run parameters.
+    @param verbose_stream The stream to which verbose output is printed. Defaults to None.
+    @return None
     """
     if verbose_stream:
         print("Linking...", file=verbose_stream)
@@ -313,13 +277,12 @@ def main(run_config: LinkerRunConfig, verbose_stream = None):
 
 def parse_args():
     """
-    Parses command-line arguments for the linker script.
+    @brief Parses command-line arguments for the linker script.
 
     This function sets up the argument parser and defines the expected arguments for the script.
     It returns a Namespace object containing the parsed arguments.
 
-    Returns:
-        argparse.Namespace: Parsed command-line arguments.
+    @return Parsed command-line arguments.
     """
     parser = argparse.ArgumentParser(
         description=("HERACLES Linker.\n"

assembler_tools/hec-assembler-tools/he_prep.py

@@ -1,22 +1,11 @@
 #! /usr/bin/env python3
 
 """
-This module provides functionality for preprocessing P-ISA abstract kernels before further assembling for HERACLES.
-
-Functions:
-    __savePISAListing(out_stream, instr_listing: list)
-        Stores instructions to a stream in P-ISA format.
-
-    main(output_file_name: str, input_file_name: str, b_verbose: bool)
-        Preprocesses the P-ISA kernel and saves the output to a specified file.
-
-    parse_args() -> argparse.Namespace
-        Parses command-line arguments for the preprocessing script.
-
-Usage:
-    This script is intended to be run as a standalone program. It requires specific command-line arguments
-    to specify input and output files and verbosity options for the preprocessing process.
+@file
+@brief This module provides functionality for preprocessing P-ISA abstract kernels before further assembling for HERACLES.
 
+This script is intended to be run as a standalone program. It requires specific command-line arguments
+to specify input and output files and verbosity options for the preprocessing process.
 """
 import argparse
 import os
@@ -31,17 +20,14 @@
 def __savePISAListing(out_stream,
                       instr_listing: list):
     """
-    Stores the instructions to a stream in P-ISA format.
+    @brief Stores the instructions to a stream in P-ISA format.
 
     This function iterates over a list of instructions and prints each instruction in P-ISA format
     to the specified output stream.
 
-    Args:
-        out_stream: The output stream to which the instructions are printed.
-        instr_listing (list): A list of instructions to be printed in P-ISA format.
-
-    Returns:
-        None
+    @param out_stream The output stream to which the instructions are printed.
+    @param instr_listing A list of instructions to be printed in P-ISA format.
+    @return None
     """
     for inst in instr_listing:
         inst_line = inst.toPISAFormat()
@@ -52,18 +38,15 @@ def main(output_file_name: str,
          input_file_name: str,
          b_verbose: bool):
     """
-    Preprocesses the P-ISA kernel and saves the output to a specified file.
+    @brief Preprocesses the P-ISA kernel and saves the output to a specified file.
 
     This function reads an input kernel file, preprocesses it to transform instructions into ASM-ISA format,
     assigns register banks to variables, and saves the processed instructions to an output file.
 
-    Args:
-        output_file_name (str): The name of the output file where processed instructions are saved.
-        input_file_name (str): The name of the input file containing the P-ISA kernel.
-        b_verbose (bool): Flag indicating whether verbose output is enabled.
-
-    Returns:
-        None
+    @param output_file_name The name of the output file where processed instructions are saved.
+    @param input_file_name The name of the input file containing the P-ISA kernel.
+    @param b_verbose Flag indicating whether verbose output is enabled.
+    @return None
     """
     # used for timings
     insts_end: int = 0
@@ -112,13 +95,12 @@ def main(output_file_name: str,
 
 def parse_args():
     """
-    Parses command-line arguments for the preprocessing script.
+    @brief Parses command-line arguments for the preprocessing script.
 
     This function sets up the argument parser and defines the expected arguments for the script.
     It returns a Namespace object containing the parsed arguments.
 
-    Returns:
-        argparse.Namespace: Parsed command-line arguments.
+    @return Parsed command-line arguments.
     """
     parser = argparse.ArgumentParser(
         description="HERACLES Assembling Pre-processor.\nThis program performs the preprocessing of P-ISA abstract kernels before further assembling.")