Logtalk automatically generates a documentation file for each compiled entity (object, protocol, or category) in <ahref="http://www.w3.org/XML/">XML</a> 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, ...).
</p>
<p>
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.
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 <atitle="Consult reference manual"href="../refman/directives/uses1.html"><code>uses/1</code></a>, <atitle="Consult reference manual"href="../refman/directives/calls1.html"><code>calls/1</code></a>, or <atitle="Consult reference manual"href="../refman/directives/mode2.html"><code>mode/2</code></a>.
Arbitrary user-defined entity information can be represented using the <atitle="Consult reference manual"href="../refman/directives/info1.html"><code>info/1</code></a> directive:
<dd>Entity author(s) (an atom or a compound term <code>{entity}</code> where <code>entity</code> is the name of a XML entity defined in the <code>custom.ent</code> file).</dd>
<dd>Parameter names for parametric entities (a list of atoms; a simpler version of the previous key, used when parameter descriptions are deemed unnecessary).</dd>
<dd>Copyright notice for the entity source code (an atom or a compound term <code>{entity}</code> where <code>entity</code> is the name of a XML entity defined in the <code>custom.ent</code> file).</dd>
<dt><code>license</code></dt>
<dd>License terms for the entity source code; usually, just the license name (an atom or a compound term <code>{entity}</code> where <code>entity</code> is the name of a XML entity defined in the <code>custom.ent</code> file).</dd>
<dd>List of general remarks about the entity using the format <em>Topic</em><code>-</code><em>Text</em>. Both the topic and the text must be atoms.</dd>
<dd>Names of predicate arguments for pretty print output (a list of atoms; a simpler version of the previous key, used when argument descriptions are deemed unnecessary).</dd>
<dd>Objects where we should define the predicate. Some possible values are <code>container</code>, <code>descendants</code>, <code>instances</code>, <code>classes</code>, <code>subclasses</code>, and <code>any</code>.</dd>
<dd>Describes if the predicate can be redefined and, if so, in what way. Some possible values are <code>never</code>, <code>free</code>, <code>specialize</code>, <code>call_super_first</code>, <code>call_super_last</code>.</dd>
<dd>List of possible exceptions throw by the predicate using the format <em>Description</em><code>-</code><em>Exception term</em>. The description must be an atom. The exception term must be a non-variable term.</dd>
<dd>List of typical predicate call examples using the format <em>Description</em><code>-</code><em>Predicate call</em><code>-</code><em>Variable bindings</em>. The description must be an atom. The predicate call term must be a non-variable term. The variable bindings term uses the format <code>{</code><em>Variable</em><code>=</code><em>Term</em>, ...<code>}</code>. When there are no variable bindings, the success or failure of the predicate call should be represented by the terms <code>{yes}</code> or <code>{no}</code>, respectively.</dd>
The XML documenting files are (by default) automatically generated when you compile a Logtalk entity. For example, assuming the default filename extensions, compiling a <code>trace</code> object and a <code>sort(_)</code> parametric object contained in a source file will result in <code>trace_0.xml</code> and <code>sort_1.xml</code> XML files.
Each XML file contains references to two other files, a XML specification file and a XSL style-sheet file. The XML specification file can be either a DTD file (<code>logtalk.dtd</code>) or a XML Scheme file (<code>logtalk.xsd</code>). The <ahref="http://www.w3.org/Style/XSL/">XSL</a> style-sheet file is responsible for converting the XML files to some desired format such as HTML or PDF. The default names for the XML specification file and the XSL style-sheet file are defined in the configuration files. The <code>xml</code> sub-directory in the Logtalk installation directory contains the XML specification files described above, along with several sample XSL style-sheet files and sample scripts for converting XML documenting files to several formats. Please read the <code>NOTES</code> file included in the directory for details. You may use the supplied sample files as a starting point for generating the documentation of your Logtalk applications.
The Logtalk DTD file, <code>logtalk.dtd</code>, contains a reference to a user-customizable file, <code>custom.ent</code>, which declares XML entities for source code author names, license terms, and copyright string. After editing the <code>custom.ent</code> file to reflect your personal data, you may use the XML entities on <code>info/1</code> documenting directives. For example, assuming that the XML entities are named <em>author</em>, <em>license</em>, and <em>copyright</em> we may write:
</p>
<pre>:- info([
version is 1.1,
author is {author},
license is {license},
copyright is {copyright}).</pre>
<p>
The entity references are replaced by the value of the corresponding XML entity when the XML documenting files are processed (<strong>not</strong> when they are generated; this notation is just a shortcut to take advantage of XML entities).
There is a set of compilers options, used with the Logtalk <atitle="Consult reference manual"href="../refman/builtins/logtalk_load2.html"><code>logtalk_load/2</code></a> or the <atitle="Consult reference manual"href="../refman/builtins/logtalk_compile2.html"><code>logtalk_compile/2</code></a> built-in predicates, that can be used to control the generation of the XML documentation files. Please see the <ahref="running.html#options">Running Logtalk</a> section of this manual for details.
