diff --git a/cli/robocompdsl/robocompdsl/common/filesgenerator.py b/cli/robocompdsl/robocompdsl/common/filesgenerator.py index bd843d70..abed4807 100644 --- a/cli/robocompdsl/robocompdsl/common/filesgenerator.py +++ b/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)