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.