diff --git a/src/fml_doc_gen/fml_doc_gen.py b/src/fml_doc_gen/fml_doc_gen.py index f41038a..ee04061 100644 --- a/src/fml_doc_gen/fml_doc_gen.py +++ b/src/fml_doc_gen/fml_doc_gen.py @@ -1,8 +1,8 @@ from typing import Callable -from fml_doc_gen import FunctionDTO -from fml_doc_gen import write_docstring_to_file -from fml_doc_gen import read_user_function -from fml_doc_gen import generate_template +from func_dto import FunctionDTO +import write_docstring_to_file +import read_user_function +import generate_template def generate_docstring_template(func: Callable, output_file: str, auto_generate: bool = False) -> str: """ diff --git a/src/fml_doc_gen/generate_template.py b/src/fml_doc_gen/generate_template.py index 255c1b4..6a33928 100644 --- a/src/fml_doc_gen/generate_template.py +++ b/src/fml_doc_gen/generate_template.py @@ -1,36 +1,84 @@ -from typing import Callable -from fml_doc_gen import FunctionDTO +from func_dto import FunctionDTO -def generate_template(func_signature: FunctionDTO) -> str: - """ - Generates a docstring template with placeholders for parameters, return values, and a brief description - based on the provided function signature. +DOCSTRING_TEMPLATE = """ + {function_name}: + ### INSERT FUNCTION DEFINITION HERE ### + {function_parameters} + {function_output} + + Examples: + -------- + ### INSERT FUNCTION EXAMPLE USAGES HERE ### +""" - Parameters +DOCSTRING_PARAMETERS_TEMPLATE = """ + Parameters: ---------- - func_signature : str - The signature of the user-defined function. + {function_params_str} +""" + +DOCSTRING_PARAMETER_TEMPLATE = """ + {param_name}: {param_type} + ### INSERT PARAMETER DEFINITION HERE ### + +""" - Returns +DOCSTRING_OUTPUT_TEMPLATE = """ + Returns: ------- - str - The docstring template with placeholders. + {function_output_type} + ### INSERT ADDITIONAL FUNCTION OUTPUT INFORMATION HERE ### +""" - Examples - -------- - >>> func_signature = "example_func(a, b)" - >>> template = generate_template(func_signature) - >>> print(template) - \"\"\"Parameters - ---------- - a : type - b : type +DOCSTRING_PARAMETER_TYPE_PLACEHOLDER = "..." - Returns - ------- - return_type - \"\"\" +def generate_template(function_signature: FunctionDTO) -> str: + """ + Generates a formatted docstring template for a function based on its name, inputs, and output type. + + Args: + function_signature (FunctionDTO): + An object containing metadata about the function, including its name, input parameters, + and output type. The `inputs` attribute should be a list of tuples where each tuple contains + the name and type of a parameter. + + Returns: + str: A string representing the generated docstring template for the function, formatted + with placeholders for detailed parameter and return value descriptions. + + Raises: + ValueError: If the `name` attribute of the `function_signature` is empty. + + Example: + >>> function_signature = FunctionDTO( + ... name="add_numbers", + ... output="int", + ... inputs=[("a", "int"), ("b", "int")] + ... ) + >>> generate_template(function_signature) """ + # Name logic + if not function_signature.name: + raise ValueError("The name of the function cannot be empty!") + function_name = function_signature.name - pass + # Parameters logic + function_params = [] + for input_name, input_type in function_signature.inputs: + function_param = DOCSTRING_PARAMETER_TEMPLATE.format( + param_name = input_name, + param_type = input_type if input_type else DOCSTRING_PARAMETER_TYPE_PLACEHOLDER) + function_params.append(function_param) + function_params_str = "".join(function_params) + function_parameters = DOCSTRING_PARAMETERS_TEMPLATE.format( + function_params_str = function_params_str) if function_params_str else "" + + # Output type + function_output_type = function_signature.output_type + function_output = DOCSTRING_OUTPUT_TEMPLATE.format(function_output_type = function_output_type) if function_output_type else "" + # Final template + return DOCSTRING_TEMPLATE.format( + function_name = function_name, + function_parameters = function_parameters, + function_output = function_output) \ No newline at end of file