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