1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
|
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta http-equiv="content-type" content="application/xml+xhtml; charset=utf-8" />
<title>Logtalk user manual: documenting programs</title>
<link rel="stylesheet" href="../screen.css" type="text/css" media="screen"/>
<link rel="stylesheet" href="../print.css" type="text/css" media="print"/>
</head>
<body>
<div class="top-left">Logtalk user manual</div>
<div class="top-right">Documenting programs</div>
<div class="bottom-left"><span class="page"/></div>
<div class="bottom-right"><span class="page"/></div>
<div class="navtop"><a href="../index.html">contents</a> > <a href="index.html">user manual</a></div>
<h1>Documenting Logtalk programs</h1>
<p>
Logtalk automatically generates a documentation file for each compiled entity (object, protocol, or category) in <a href="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.
</p>
<h2>Documenting directives<a id="directives"></a></h2>
<p>
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 <a title="Consult reference manual" href="../refman/directives/uses1.html"><code>uses/1</code></a>, <a title="Consult reference manual" href="../refman/directives/calls1.html"><code>calls/1</code></a>, or <a title="Consult reference manual" href="../refman/directives/mode2.html"><code>mode/2</code></a>.
</p>
<h3>Entity directives<a id="entity"></a></h3>
<p>
Arbitrary user-defined entity information can be represented using the <a title="Consult reference manual" href="../refman/directives/info1.html"><code>info/1</code></a> directive:
</p>
<pre>:- info([
Key1 is Value1,
Key2 is Value2,
...]).</pre>
<p>
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:
</p>
<blockquote>
<dl>
<dt><code>comment</code></dt>
<dd>Comment describing entity purpose (an atom).</dd>
<dt><code>author</code></dt>
<dd>Entity author (an atom).</dd>
<dt><code>version</code></dt>
<dd>Version number (a number).</dd>
<dt><code>date</code></dt>
<dd>Date of last modification (formatted as Year/Month/Day).</dd>
<dt><code>parameters</code></dt>
<dd>Parameter names and descriptions for parametric entities (a list of key-values where both keys and values are atoms).</dd>
<dt><code>parnames</code></dt>
<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>
<dt><code>remarks</code></dt>
<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>
</dl>
</blockquote>
<p>
For example:
</p>
<pre>:- info([
version is 2.1,
author is 'Paulo Moura',
date is 2000/4/20,
comment is 'Building representation.',
diagram is 'UML Class Diagram #312']).</pre>
<p>
Use only the keywords that make sense for your application and remember that you are free to invent your own keywords.
</p>
<h3>Predicate directives<a id="predicate"></a></h3>
<p>
Arbitrary user-defined predicate information can be represented using the
<a title="Consult reference manual" href="../refman/directives/info2.html"><code>info/2</code></a> directive:
</p>
<pre>:- info(Functor/Arity, [
Key1 is Value1,
Key2 is Value2,
...]).</pre>
<p>
Keys should be atoms and values should be ground terms. The following keys are pre-defined and may be processed specially by Logtalk:
</p>
<blockquote>
<dl>
<dt><code>comment</code></dt>
<dd>Comment describing predicate purpose (an atom).</dd>
<dt><code>arguments</code></dt>
<dd>Names and descriptions of predicate arguments for pretty print output (a list of key-values where both keys and values are atoms).</dd>
<dt><code>argnames</code></dt>
<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>
<dt><code>allocation</code></dt>
<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>
<dt><code>redefinition</code></dt>
<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>
<dt><code>exceptions</code></dt>
<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>
<dt><code>examples</code></dt>
<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>
</dl>
</blockquote>
<p>
For example:
</p>
<pre>:- info(color/1, [
comment is 'Table of defined colors.',
argnames is ['Color'],
constraint is 'Only a maximum of four visible colors allowed.']).</pre>
<p>
Use only the keywords that make sense for your application and remember that you are free to invent your own keywords.
</p>
<h2>Processing and viewing documenting files<a id="processing"></a></h2>
<p>
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.
</p>
<p>
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 <a href="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.
</p>
<p>
There is a set of compilers options, used with the Logtalk <a title="Consult reference manual" href="../refman/builtins/logtalk_load2.html"><code>logtalk_load/2</code></a> or the <a title="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 <a href="running.html#options">Running Logtalk</a> section of this manual for details.
</p>
<div class="footer">
<div class="navbottom"><a href="errors.html">previous</a> | <a href="../glossary.html">glossary</a> | <a href="installing.html">next</a></div>
<div class="copyright">Copyright © <a href="mailto:pmoura@logtalk.org">Paulo Moura</a> — <a href="http://www.logtalk.org">Logtalk.org</a></div>
<div class="footnote">
<span class="validators"><a href="http://validator.w3.org/check/referer">XHTML</a> + <a href="http://jigsaw.w3.org/css-validator/check/referer">CSS</a></span>
<span class="date">Last updated on: November 16, 2005</span>
</div>
</div>
</body>
</html>
|
