Documentation Generation Library

Author(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 output format in which the documentation is generated is defined by the backend modules (autodoc_texinfo, autodoc_html, autodoc_man, etc.).

One of 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). There is also some limited support for direct output in unix man format. 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 a reference manual is included with the library source code. Other examples can be found in the Ciao documentation directory (i.e., the Ciao manuals themselves).

Documentation on exports

PREDICATE

Usage:index_comment(Index,Text)

Type is a type of index which is supported. Text describes the index contents.

  • The following properties should hold upon exit:
    (atom/1)Index is currently instantiated to an atom.
    (string/1)Text is a string (a list of character codes).

PREDICATE
No further documentation available for this predicate.

PREDICATE

Usage:ensure_output_dir_prepared(Backend,Opts)

Ensure that the output directories for backend Backend are prepared.

    PREDICATE

    Usage:get_autodoc_opts(Backend,Mod,Opts)

    Get the list of documentation options Opts for the FileBase file.

    • The following properties should hold at call time:
      (atm/1)Backend is an atom.
      (atm/1)Mod is an atom.
      (list/2)Opts is a list of supported_options.

    PREDICATE

    Usage:autodoc_gen_doctree(Backend,FileBase,FileExt,Opts,Mod)

    FileBase is the module specifier of the source file being documented (without extension, FileExt is the source extension). 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.
      (filename_noext/1)FileBase is the base name of a file (without extension).
      (atm/1)FileExt is an atom.
      (list/2)Opts is a list of supported_options.
      (atm/1)Mod is an atom.

    PREDICATE

    Usage:fmt_infodir_entry(DocSt,Version,Mod)

    Generates a one line description (ASCII) of the application or library in a file for the directory of emacs info manuals.

    PREDICATE

    Usage:

    Compute the globally resolved references (including bibliography)

      PREDICATE

      Usage:

      Translate the doctree using the specific backend

        PREDICATE
        No further documentation available for this predicate.

        PREDICATE
        No further documentation available for this predicate.

        Documentation on multifiles

        PREDICATE
        No further documentation available for this predicate. The predicate is multifile.

        PREDICATE
        No further documentation available for this predicate. The predicate is multifile.