Documented 11 functions across 1 file

cli/robocompdsl/robocompdsl/common/filesgenerator.py

@@ -24,6 +24,11 @@
 
 class FilesGenerator:
     def __init__(self):
+        """
+        sets instance attributes for a `CodeDocumentor` object: `self.__dsl_file`,
+        `self.__output_path`, `self.__include_dirs`, `self.diff`, and `self.ast`.
+
+        """
         self.__dsl_file = None
         self.__output_path = None
         self.__include_dirs = None
@@ -36,6 +41,16 @@ def dsl_file(self):
 
     @dsl_file.setter
     def dsl_file(self, value):
+        """
+        takes a string parameter `value` and ensures that it is a valid file path
+        exists in the file system, setting its internal variable `self.__dsl_file`
+        to the given value.
+
+        Args:
+            value (str): DSL file path that the function modifies the `self.__dsl_file`
+                attribute with.
+
+        """
         assert isinstance(value, str), "dsl_file must be a string not %s" % str(type(value))
         assert os.path.exists(value), "%s dsl file not found." % value
         self.__dsl_file = value
@@ -46,6 +61,15 @@ def output_path(self):
 
     @output_path.setter
     def output_path(self, value):
+        """
+        takes a string parameter `value` and assigns it to the class attribute
+        `__output_path`. It throws an error if the input is not a string.
+
+        Args:
+            value (str): path to the output file that is assigned to the `__output_path`
+                attribute of the object instance.
+
+        """
         assert isinstance(value, str), "output_path must be a string not %s" % str(type(value))
         self.__output_path = value
 
@@ -55,10 +79,35 @@ def include_dirs(self):
 
     @include_dirs.setter
     def include_dirs(self, value):
+        """
+        takes a list of directories as input and sets them as instance attribute
+        `self.__include_dirs`.
+
+        Args:
+            value (list): list of directories to include in the documentation generation.
+
+        """
         assert isinstance(value, list), "include_dirs must be a string not %s" % str(type(value))
         self.__include_dirs = value
 
     def generate(self, input_file, output_path, include_dirs, diff=None, test=False):
+        """
+        generates high-quality documentation for given code, using the `dsl_file`,
+        `output_path`, `include_dirs`, `diff`, and `test` inputs. It creates new
+        files based on the AST of the input code, displays any differences between
+        the original and existing files, and returns the new files.
+
+        Args:
+            input_file (str): code file to be documentation.
+            output_path (str): directory where the generated documentation will
+                be saved.
+            include_dirs (list): directories to be included in the search for
+                dependencies when generating documentation.
+            diff (None): difference between the original file and the expected
+                output, which is calculated and displayed by the `generate` function.
+            test (bool):
+
+        """
         self.dsl_file = input_file
         self.output_path = output_path
         self.include_dirs = include_dirs
@@ -68,6 +117,12 @@ def generate(self, input_file, output_path, include_dirs, diff=None, test=False)
         self.__show_diff(new_existing_files)
 
     def __load_ast(self):
+        """
+        parses a DSL file and returns an AST if there are no parsing errors. If
+        any exceptions occur, it displays an error message and exits with a non-zero
+        status code.
+
+        """
         try:
             self.ast = dsl_factory.DSLFactory().from_file(self.dsl_file, include_directories=self.include_dirs)
         except ValueError as e:
@@ -87,6 +142,18 @@ def __load_ast(self):
 
 
     def __create_files(self, test=False):
+        """
+        creates and updates existing files in a project based on its input `test`
+        parameter. It recursively generates component and interface files as needed.
+
+        Args:
+            test (bool): boolean value for testing whether files should be generated
+                or not in the `create_files()` function.
+
+        Returns:
+            dict: a dictionary of existing files.
+
+        """
         new_existing_files = {}
         if self.dsl_file.endswith(".cdsl") or self.dsl_file.endswith(".jcdsl"):
             # Check output directory
@@ -101,6 +168,15 @@ def __create_files(self, test=False):
 
     def __show_diff(self, new_existing_files):
         # Code to launch diff tool on .new files to be compared with their old version
+        """
+        compares new and existing files using a diff tool and launches the tool
+        if there are differences.
+
+        Args:
+            new_existing_files (dict): .new files to be compared with their old
+                version by launching diff tool to detect changes.
+
+        """
         if self.diff is not None and len(new_existing_files) > 0:
             diff_tool, _ = robocompdslutils.get_diff_tool(prefered=self.diff)
             console.log("Executing diff tool for existing files. Close if no change is needed.")
@@ -123,6 +199,32 @@ def __show_diff(self, new_existing_files):
                     console.log("Binary equal files %s and %s" % (o_file, n_file))
 
     def __generate_component(self, test):
+        """
+        generates files for a Python or C++ component based on its AST representation,
+        adding them to a list of new and existing files in the output path.
+
+        Args:
+            test (object reference or variable.): status of template generation
+                for Python templates, affecting the execution path of the function.
+
+                		- `test`: The input data passed to the function for generating
+                the component files. Its type is inferred from the function's
+                signature and cannot be specified explicitly.
+
+                	The `test` variable may have the following properties or attributes:
+
+                		- `language`: The programming language of the AST, which determines
+                the template engine used for generating files (python or cpp).
+                		- `ast`: The abstract syntax tree of the code being generated,
+                containing the structure and semantics of the code.
+                		- `output_path`: The path where the generated files should be saved.
+
+
+        Returns:
+            list: a dictionary containing the list of new existing files generated
+            for the given code and language.
+
+        """
         language = self.ast.language.lower()
 
         template = LANG_TO_TEMPLATE[language]
@@ -151,11 +253,30 @@ def __generate_component(self, test):
         return new_existing_files
 
     def __generate_interface(self):
+        """
+        creates and produces new files based on an existing Ast structure using a
+        template manager object and returns the resultant new or existing files.
+
+        Returns:
+            list: a list of existing or new files generated in the specified output
+            path based on the AstNode tree.
+
+        """
         template_obj = TemplateManagerIce(self.ast)
         new_existing_files = template_obj.generate_files(self.output_path)
         return new_existing_files
 
     def __create_component_directories(self, test=False):
+        """
+        generates high-quality documentation for code. It creates directories
+        within the output directory and one additional directory inside the output
+        directory for testing purposes if `test` is True.
+
+        Args:
+            test (bool): boolean value indicating whether to create the test
+                directories within the output directory.
+
+        """
         if not os.path.exists(self.output_path):
             robocompdslutils.create_directory(self.output_path)