mix lazy_doc (LazyDoc v0.5.0)

## Main functionality

The module Mix.Tasks.LazyDoc provides a Mix task for processing source files to extract and format documentation for Elixir modules and functions.

## Description

It enables the extraction of documentation using AI to enhance the documentation generation process, verifying and formatting documentation as per specified requirements. It handles reading the source code, interacting with a provider for documentation prompts, and writing the results back in a structured format.

Summary

Functions

Parameters

  • docs - a binary string that represents documentation text.

Description

Checks if the provided documentation string is formatted correctly with an appropriate @doc tag.

Parameters

  • docs - the documentation string that needs to be converted into an Abstract Syntax Tree (AST).
  • acc_ast - the accumulator Abstract Syntax Tree that will be updated.
  • module_ast - the module's AST where the documentation will be inserted.

Description

Converts a documentation string into an Elixir AST and inserts it into the specified module AST.

Parameters

  • ast - the abstract syntax tree representing the module.
  • name_func - the name of the function to be documented.
  • ast_doc - the documentation to be inserted for the function.
  • module_ast - the abstract syntax tree of the module where the function resides.

Description

Inserts documentation for a specified function within a given module.

Parameters

  • ast - the abstract syntax tree to be transformed.
  • module_ast - the specific module's abstract syntax tree that is being targeted for documentation.
  • ast_doc - the documentation string to be inserted into the module.

Description

Inserts documentation into the specified module's AST, either as a new block or by prepending it to an existing block.

Parameters

  • module - the module in which the nodes will be inserted.
  • module_ast - the abstract syntax tree representation of the module.
  • functions - a list of function tuples containing function name atoms and their string representations.
  • final_prompt - the prompt string used for generating documentation.
  • provider_mod - the module responsible for provider-specific requests.
  • model_text - the text input to the model used for processing the prompt.
  • token - the authorization token for API requests.
  • params - additional parameters passed to the request.
  • acc - the accumulator for building the resulting abstract syntax tree.

Description

Inserts documentation nodes into a module based on specified functions and prompts.

Parameters

  • entries - a list of entries containing module and function information for processing.

Description

Processes a list of entries to generate documentation based on the specified provider configuration.

Parameters

  • _command_line_args - command line arguments passed to the function.

Description

Starts required applications and processes configuration, while extracting data from files.

Parameters

  • file - the name of the file to which the data will be written.
  • ast - the Abstract Syntax Tree (AST) representation to be converted to a string and written to the file.

Description

Writes the string representation of the given AST to the specified file.

Parameters

  • file - The path to the file where the formatted output will be written.
  • ast - The abstract syntax tree (AST) that needs to be converted to a string representation.
  • comments - Optional comments to include in the formatted output.

Description

Formats the given abstract syntax tree and writes it to the specified file.

Functions

docs_are_ok?(docs)

Parameters

  • docs - a binary string that represents documentation text.

Description

Checks if the provided documentation string is formatted correctly with an appropriate @doc tag.

Returns

true if the documentation matches the expected format, false otherwise.

docs_to_module_doc_node(docs, acc_ast, module_ast)

Parameters

  • docs - the documentation string that needs to be converted into an Abstract Syntax Tree (AST).
  • acc_ast - the accumulator Abstract Syntax Tree that will be updated.
  • module_ast - the module's AST where the documentation will be inserted.

Description

Converts a documentation string into an Elixir AST and inserts it into the specified module AST.

Returns

The updated accumulator Abstract Syntax Tree after the documentation has been inserted.

insert_doc_for_function(ast, name_func, ast_doc, module_ast)

Parameters

  • ast - the abstract syntax tree representing the module.
  • name_func - the name of the function to be documented.
  • ast_doc - the documentation to be inserted for the function.
  • module_ast - the abstract syntax tree of the module where the function resides.

Description

Inserts documentation for a specified function within a given module.

Returns

The modified abstract syntax tree with the new documentation for the function added.

insert_module_doc(ast, module_ast, ast_doc)

Parameters

  • ast - the abstract syntax tree to be transformed.
  • module_ast - the specific module's abstract syntax tree that is being targeted for documentation.
  • ast_doc - the documentation string to be inserted into the module.

Description

Inserts documentation into the specified module's AST, either as a new block or by prepending it to an existing block.

Returns

The modified abstract syntax tree with the documentation inserted into the desired module.

insert_nodes_in_module(arg, final_prompt, provider_mod, model_text, token, params, acc)

Parameters

  • module - the module in which the nodes will be inserted.
  • module_ast - the abstract syntax tree representation of the module.
  • functions - a list of function tuples containing function name atoms and their string representations.
  • final_prompt - the prompt string used for generating documentation.
  • provider_mod - the module responsible for provider-specific requests.
  • model_text - the text input to the model used for processing the prompt.
  • token - the authorization token for API requests.
  • params - additional parameters passed to the request.
  • acc - the accumulator for building the resulting abstract syntax tree.

Description

Inserts documentation nodes into a module based on specified functions and prompts.

Returns

The updated abstract syntax tree with documentation nodes inserted.

proccess_files(entries)

Parameters

  • entries - a list of entries containing module and function information for processing.

Description

Processes a list of entries to generate documentation based on the specified provider configuration.

Returns

None, the function writes processed documentation to files.

run(command_line_args)

Parameters

  • _command_line_args - command line arguments passed to the function.

Description

Starts required applications and processes configuration, while extracting data from files.

Returns

None

write_to_file(file, ast)

Parameters

  • file - the name of the file to which the data will be written.
  • ast - the Abstract Syntax Tree (AST) representation to be converted to a string and written to the file.

Description

Writes the string representation of the given AST to the specified file.

Returns

None

write_to_file_formatted(file, ast, comments)

Parameters

  • file - The path to the file where the formatted output will be written.
  • ast - The abstract syntax tree (AST) that needs to be converted to a string representation.
  • comments - Optional comments to include in the formatted output.

Description

Formats the given abstract syntax tree and writes it to the specified file.

Returns

The result of the file write operation, indicating success or failure.