Documentation Generation LibraryAuthor(s): Manuel Hermenegildo, Jose F. Morales.
This library provides some predicates which generate documentation automatically for a given module or application, using the declarations and assertions used in the module itself as input (see the assertions library). By default, only the exported predicates of the module appear in the documentation. The predicates will be documented in the order in which they appear in the module/1 or module/2 declaration.
The idea of this package is on one hand to reuse the information present in the assertions and on the other to help ensure that code and documentation are kept as coherent as possible. Hopefully, keeping them close together should help in this always difficult task. The resulting documentation is somewhat rigidly structured, but generally sufficient for a reference manual, provided a little effort is put into the assertions and comments. The end product understandably depends heavily on how much work is put into adding additional comments to the source. Some documentation will be generated in any case, but it is recommended that, at the minimum, a module title and a comment for each of the exported predicates be provided.
The main output format supported is texinfo (see The GNU Texinfo Documentation System manual for more info), from which printed manuals and several other printing and on-line formats can be easily generated automatically (including info, html, etc.). There is also some limited support for direct output in unix man format and direct html (but note that html can also be generated in a better way by first generating texinfo and then using one of the available converters). For texinfo, the documentation for a module is a texinfo chapter, suitable for inclusion in a wrapper “main” document file. A simple example of the use of this library for generating a texinfo reference manual (including a driver script, useful Makefiles, etc.) is included with the library source code. Other examples can be found in the Ciao documentation directory (i.e., the Ciao manuals themselves).
A simple example of the use of this library for generating a texinfo reference manual (including a driver script, useful Makefiles, etc.) is included with the library source code. Other examples can be found in the Ciao documentation directory (i.e., the Ciao manuals themselves).
Usage and interface
- Library usage:
index_comment/2, reset_output_dir_db/0, ensure_output_dir_prepared/2, get_autodoc_opts/3, autodoc_gen_doctree/5, fmt_infodir_entry/3, autodoc_compute_grefs/3, autodoc_translate_doctree/3, autodoc_finish/1, autodoc_gen_alternative/2.
- Other modules used:
- Application modules:
lpdocsrc(src(autodoc_state)), lpdocsrc(src(autodoc_settings)), lpdocsrc(src(autodoc_filesystem)), lpdocsrc(src(autodoc_structure)), lpdocsrc(src(autodoc_doctree)), lpdocsrc(src(autodoc_refsdb)), lpdocsrc(src(autodoc_parse)), lpdocsrc(src(autodoc_index)), lpdocsrc(src(comments)), lpdocsrc(src(autodoc_html_resources)), lpdocsrc(src(autodoc_texinfo)).
- System library modules:
format, ttyout, aggregates, read, make/make_rt, dict, compiler/compiler, assertions/assrt_lib, compiler/c_itf, assertions/assertions_props, messages, filenames, lists, terms, make/system_extra, system.
- Internal (engine) modules:
term_basic, arithmetic, atomic_basic, attributes, basic_props, basiccontrol, data_facts, exceptions, io_aux, io_basic, prolog_flags, streams_basic, system_info, term_compare, term_typing, hiord_rt, debugger_support.
- Application modules:
Documentation on exports
- Description: Ensure that the output directories for backend Backend are prepared.
- Description: FileBase is the module specifier of the source file being documented (without extension, SourceSuffix is the suffix of the source). The output is a file whose contents document the main file, based on any assertions present in that file. The documentation is produced in the format given by Backend (the name of the output file also depends on Backend). The formats supported are given by backend_id/1.
- Call and exit should be compatible with:
(backend_id/1)Backend is a supported backend.
(basename/1)FileBase is the base name of a file (without extension).
(atm/1)SourceSuffix is an atom.
(list/2)Opts is a list of supported_options.
(atm/1)Mod is an atom.
- Description: Generates a one line description (ASCII) of the application or library in a file for the directory of emacs info manuals.
- The following properties should hold at call time:
(term/1)Version is any term.
(basename/1)Mod is the base name of a file (without extension).
- Description: Compute the globally resolved references (including bibliography)
- Description: Translate the doctree using the specific backend