Logtalk user manual: documenting programs

contents > user manual

# Documenting Logtalk programs

Logtalk automatically generates a documentation file for each compiled entity (object, protocol, or category) in XML format. Contents of the XML file include the entity name, type, and compilation mode (static or dynamic), the entity relations with other entities, and a description of any declared predicates (name, compilation mode, scope, ...).

The XML documentation files can be enriched with arbitrary user-defined information, either about an entity or about its predicates, by using the two directives described below.

## Documenting directives

Logtalk supports two documentation directives for providing arbitrary user-defined information about an entity or a predicate. These two directives complement other Logtalk directives that also provide important documentation information like `uses/1`, `calls/1`, or `mode/2`.

### Entity directives

Arbitrary user-defined entity information can be represented using the `info/1` directive:

        :- info([
            Key1 is Value1,
            Key2 is Value2,
            ...]).

In this pattern, keys should be atoms and values should be ground terms. The following keys are pre-defined and may be processed specially by Logtalk:

> `comment`
>   Comment describing entity purpose (an atom).
> `author`
>   Entity author (an atom).
> `version`
>   Version number (a number).
> `date`
>   Date of last modification (formatted as Year/Month/Day).
> `parnames`
>   Parameter names for parametric entities (a list of atoms).

For example:

        :- info([
            version is 2.1,
            author is 'Paulo Moura',
            date is 2000/4/20,
            comment is 'Building representation.',
            diagram is 'UML Class Diagram #312']).

Use only the keywords that make sense for your application and remember that you are free to invent your own keywords.

### Predicate directives

Arbitrary user-defined predicate information can be represented using the `info/2` directive:

        :- info(Functor/Arity, [
            Key1 is Value1,
            Key2 is Value2,
            ...]).

Keys should be atoms and values should be ground terms. The following keys are pre-defined and may be processed specially by Logtalk:

> `comment`
>   Comment describing predicate purpose (an atom).
> `argnames`
>   Names of predicate arguments for pretty print output (a list of atoms).
> `allocation`
>   Objects where we should define the predicate. Some possible values are `container`, `descendants`, `instances`, `classes`, `subclasses`, and `any`.
> `redefinition`
>   Describes if the predicate can be redefined and in what way. Some possible values are `never`, `free`, `specialize`, `call_super_first`, `call_super_last`.

For example:

        :- info(color/1, [
            comment is 'Table of defined colors.',
            argnames is ['Color'],
            constraint is 'Only a maximum of four visible colors allowed.']).

Use only the keywords that make sense for your application and remember that you are free to invent your own keywords.

## Processing and viewing documenting files

The XML documenting files are (by default) automatically generated when you compile a Logtalk entity. For example, assuming the default filename extensions, compiling a `sort1.lgt` file generates a `sort1.pl` Prolog file and a `sort1.xml` XML file. The filename extension for each kind of file can be changed in the config files via the `lgt_file_extension/2` predicate.

Each XML file contains references to two other files: `logtalk.dtd`, a DTD file describing the XML file structure, and a XSL style sheet file responsible for converting the XML files to some desired format like HTML. The name of the XSL file can be changed in the configuration files via the `lgt_file_name/2` predicate. The default value is `lgtxml.xsl`, a XSL file that enables Logtalk XML files to be viewed directly in a web browser. The HTML output refers a CSS file, `logtalk.css`, that specifies how the HTML code will be rendered. The three default files are contained in the `xml` sub-directory in the Logtalk installation directory. This directory may also contain other files for specific XSLT processors or for converting XML to other formats besides HTML. Please read the `NOTES` file included in the directory for details.

There is a set of compilers options, used with the Logtalk `logtalk_load/2` or the `logtalk_compile/2` built-in predicates, that can be used to control the generation of the XML documentation files. Please see the Installing and running Logtalk section of this manual for details.

By default, all file references use relative paths, assuming that the `.xml` documentation files and the `.dtd`, `.xsl`, and `.css` files reside in the same directory. This can acomplished either by copying the DTD and style files to the your application compiling directory or by using file aliases or symbolic links, depending on the operating system that you are using. Of course, you may also copy the `*.xml` files to the `xml` sub-directory.

To view the XML documenting files you can open them in a web browser that supports the XML, XSL, CSS 1, and HTML 4 standards or use a XSLT tool to compile the `.xml` files to `.html` files. You can also write new XSL files to convert the XML code to alternative formats like LaTeX or any other desired format.

previous | glossary | next
Copyright © Paulo Moura — Logtalk.org