Dependencies: lib_2da, lib_anon, lib_array, lib_fn, lib_ini, lib_math, lib_sfo, lib_struct, lib_sugar, lib_tools
Dedicated library to document a set of WEIDU function libraries and work out their dependencies. Documentation is pulled directly from the tph/tpa file.
To document a function, use this notation in a comment somewhere in your TPH:
document{my_function} {Description of the function.}
To put a description of the whole library, use this:
describe-library
{
Description of the library
}
To mark a variable as Boolean, Array, Function or Switch, use this sort of notation
INT_VAR
b=0//boolean
i=0
STR_VAR
f=""//function
a=""//array
c=""//[upper|lower]
funlib_document_component(component_loc:s)=() dimorphic
Particular application of funlib_document_libraries that documents all tpa/tph files in a directory, setting extra_path to the sfo library directory.
funlib_document_libraries(library_path:s="MOD_FOLDER/sfo", library_array:a, extra_path:s, extra_array:s, style_path:s="../../doc/files", resource_path:s="MOD_FOLDER/sfo", template_path:s="MOD_FOLDER/sfo/resource/doc_template.html", doc_path:s="MOD_FOLDER/sfo/doc", ignore:s="MOD_FOLDER/sfo/data/weidu_functions.2da")=() dimorphic
Given either an array of libraries in the form file=>path, or a path to a directory of libraries (assumed to be all and only the tph/tpa files) generate HTML documentation for each library. MOD_FOLDER/sfo/resource/doc_template.html points to the HTML template into which we substitute the data. ../../doc/files points to the location of the css files and similar. doc_path is where you want them to go. Functions listed in the 'ignore' 2da (by default, the weidu built-in functions) are ignored. If 'extra_array' or 'extra_path' are set, the libraries contained in the array or on the path are included for dependencies but not documented.
funlib_get_dependencies(recursive:i=1, library_array:a, ignore:s="MOD_FOLDER/sfo/data/weidu_functions.2da")=(dependency_map:a, missing_map:a, internal_map:a) action
Given an array of libraries in the format file=>path, find all the dependencies and return them in a 2d array in format (dependent_library,required_library)=>_.
Also return a 2d array of functions that are used in the libraries but not defined in any of them, in the format (library, function_it_uses)=>_.
Also return a 2d array of libraries that use internal functions, in the format (library,function_it_uses)=>_
Functions in the zeroth column of the 2da file 'ignore' (by default, a list of all the predefined WEIDU functions) are ignored.
funlib_get_function_descriptions(path:s, file:s)=(function_descriptions:a) action
Process the given file to get an 3d array of form (function_name,function_type,comment)->nicely_processed_description_of_spec.
funlib_get_function_locations(library_array:a)=(function_locations:a, function_locations_singular:a, internal_functions:a) action
Given either an array of libraries in the format file=>path, or a path to a directory of libraries (with tpa/tph suffixes), go through all the libraries and get where each function is. Return it in a 2d array in the form (function,library)=>_. Also return a 1d array in the form function=>_ of all the internal functions. Also return a 1d array in the form function=>library, that contains an arbitrary library where the function is.
(I mean, functions shouldn't be multiply defined. But sometimes they are.)
funlib_get_functions_documented(file:s, path:s)=(library_doc:s, technical_note:s, function_docs:a) action
Return a function-name=>function-description array of all function descriptions in the specified library, as well as the overall library description (if any). Also return 'library_doc' and 'technical_doc', which code more advanced details
funlib_list_external_functions(file:s, path:s, location:s, locbase:s, library_array:a, library_path:s, ignore:s="MOD_FOLDER/sfo/data/weidu_functions.2da")=(external_functions:a) action
funlib_report_dependencies(recursive:i=1, library_path:s, library_array:a, ignore:s="MOD_FOLDER/sfo/data/weidu_functions.2da")=() dimorphic
Given either an array of libraries in the form file=>path, or a path to a directory of libraries (assumed to be all and only the tph/tpa files), generate a report in the data_loc directory on dependencies, missing functions, and use of internal functions. If recursive=1, close dependency relations transitively.
These should not be called from outside the library itself.
funlib_extract_function_data()=(function_data:a) patch
Destructively process the current file (assumed to be a tpx file) and return a 3d array of the function spec blocks (everything up to the BEGIN) in the format (function_name,function_type,function_comment=>function_spec. (Function_type is action, patch or dimorphic.)
funlib_get_functions_defined()=(functions_defined:a) patch
Return a k=>v array of all functions defined in the currently-being-patched library, where v is the comment if any.
funlib_get_functions_used(file:s, path:s, location:s, locbase:s)=(functions_used:a) action
Return a k=>_ array of all functions used (via LAF/LPF) in the specified library.)
funlib_get_library_array(library_path:s)=(library_array:a) dimorphic
Go through the given directory and return an array of tpa/tph files, in the format file->path (path is the same for all).
funlib_process_document_lines(type:s)=(data:s) dimorphic
]*{\([^