LazyDoc (LazyDoc v0.5.0)
## Main functionality
The module LazyDoc provides a way to extract and organize documentation from Elixir source files by reading them, parsing their abstract syntax tree (AST), and collecting relevant information about modules, functions, and comments.
## Description
It implements functions to read files matching a given path pattern, extract their AST and comments, group function definitions by names and arities, filter out undocumented functions and modules, and retrieve associated documentation for the extracted modules. The module serves as a utility for generating or managing documentation for Elixir projects.
Summary
Functions
Parameters
- modules - a list of modules to fetch documentation for.
Description
Retrieves the documentation for the specified modules, filtering to include only the functions.
Parameters
- patterns - a list of regular expressions used to filter file paths.
- @global_path - a global variable representing the directory path to search for files.
Description
Extracts data from files in the specified paths by reading the file contents, parsing them into an abstract syntax tree (AST), and extracting module and function information.
Parameters
- ast - The abstract syntax tree (AST) from which names will be extracted.
- acc - An accumulator that stores the collected names.
Description
Extracts module, function, and protocol names from the given abstract syntax tree.
Parameters
- module - the module to process.
- module_ast - the abstract syntax tree of the module.
- _code_mod - the code modification that is being applied (unused).
- functions - a list of functions to filter.
Description
Filters the provided functions based on their visibility in the documentation.
Parameters
- module - The name of the module being analyzed.
- module_ast - The abstract syntax tree (AST) representation of the module.
- _code_mod - The code representation of the module, not used in the function.
- functions - A list of functions in the module.
Description
Filters the list of functions in a module to identify those that are undocumented.
Parameters
- zip_to_process - a list of tuples containing module information, where each tuple consists of the module name, its abstract syntax tree (AST), code, and function documentation.
Description
Filters out modules that do not contain any documentation.
Parameters
- func_docs - a list of tuples containing function documentation details.
Description
Groups function documentation by function name.
Parameters
- names - a list of tuples where each tuple contains a type and a name with code.
Description
Recursively processes a list of name-code tuples to generate a list of joined code based on matching names.
Functions
@spec docs_per_module([module(), ...]) :: [ {module :: module(), module_doc :: doc_content, docs :: [doc_element]}, ... ] when annotation: :erl_anno.anno(), doc_content: %{optional(binary()) => binary()} | :none | :hidden, doc_element: {{kind :: atom(), function_name :: atom(), arity()}, annotation, signature, doc_content, metadata}, signature: [binary()], metadata: map()
Parameters
- modules - a list of modules to fetch documentation for.
Description
Retrieves the documentation for the specified modules, filtering to include only the functions.
Returns
A list of tuples containing each module and its corresponding documentation details.
Parameters
- patterns - a list of regular expressions used to filter file paths.
- @global_path - a global variable representing the directory path to search for files.
Description
Extracts data from files in the specified paths by reading the file contents, parsing them into an abstract syntax tree (AST), and extracting module and function information.
Returns
A list of maps, each containing details about the file, including its content, AST, extracted functions, documented functions, undocumented functions, modules, and any comments found.
Parameters
- ast - The abstract syntax tree (AST) from which names will be extracted.
- acc - An accumulator that stores the collected names.
Description
Extracts module, function, and protocol names from the given abstract syntax tree.
Returns
A list of tuples containing the extracted names and their corresponding structures.
Parameters
- module - the module to process.
- module_ast - the abstract syntax tree of the module.
- _code_mod - the code modification that is being applied (unused).
- functions - a list of functions to filter.
Description
Filters the provided functions based on their visibility in the documentation.
Returns
A tuple containing the module, its abstract syntax tree, and the filtered list of functions.
Parameters
- module - The name of the module being analyzed.
- module_ast - The abstract syntax tree (AST) representation of the module.
- _code_mod - The code representation of the module, not used in the function.
- functions - A list of functions in the module.
Description
Filters the list of functions in a module to identify those that are undocumented.
Returns
A tuple containing the module name, its AST, and the filtered list of undocumented functions.
Parameters
- zip_to_process - a list of tuples containing module information, where each tuple consists of the module name, its abstract syntax tree (AST), code, and function documentation.
Description
Filters out modules that do not contain any documentation.
Returns
A list of modules, each represented as a tuple containing the module name, AST, and code.
Parameters
- func_docs - a list of tuples containing function documentation details.
Description
Groups function documentation by function name.
Returns
a map where each key is a function name and the value is a list of documentation strings associated with that function.
Parameters
- names - a list of tuples where each tuple contains a type and a name with code.
Description
Recursively processes a list of name-code tuples to generate a list of joined code based on matching names.
Returns
A list of functions or tuples based on the input names.