/usr/share/doc/gnat-gps/html/Documentation-Generation.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Copyright (C) 2002-2010 AdaCore.

This document is free; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This document is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License along
with this program; if not, see http://www.gnu.org/licenses/.

A copy of the license is included in the section entitled
"GNU General Public License". -->
<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ -->
<head>
<title>Using the GNAT Programming Studio: Documentation Generation</title>

<meta name="description" content="Using the GNAT Programming Studio: Documentation Generation">
<meta name="keywords" content="Using the GNAT Programming Studio: Documentation Generation">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="Index-table.html#Index-table" rel="index" title="Index table">
<link href="Tools.html#Tools" rel="up" title="Tools">
<link href="Metrics.html#Metrics" rel="next" title="Metrics">
<link href="Code-Fixing.html#Code-Fixing" rel="previous" title="Code Fixing">
<style type="text/css">
<!--
   

a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.indentedblock {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
div.smalllisp {margin-left: 3.2em}
kbd {font-style:oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nocodebreak {white-space:nowrap}
span.nolinebreak {white-space:nowrap}
span.roman {font-family:serif; font-weight:normal}
span.sansserif {font-family:sans-serif; font-weight:normal}
ul.no-bullet {list-style: none}
pre.smallexample {background-color:rgb(240,240,240);
                     font-family: courier new,courier,fixed;
                     font-size: 14px;
                     margin: 0px 40px 0px 40px;
                     border-width: 1px 2px 2px 1px;
                     border-top-style: dotted;
                     border-left-style: dotted;
                     border-right-style: solid;
                     border-bottom-style: solid;
                     border-color: black;}
   code             {color:black;
                     font-family: courier new,courier,fixed;
                     font-size: 14px;}
   body             {font-family: arial,helvetica,sans-serif;
                     font-size: 16px;
                     max-width: 800px;
                     text-align: justify}
   samp             {font-family: courier new,courier,fixed;
                     font-size: 14px}
                    

-->
</style>


</head>

<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="Documentation-Generation"></a>
<div class="header">
<p>
Next: <a href="Metrics.html#Metrics" accesskey="n" rel="next">Metrics</a>, Previous: <a href="Code-Fixing.html#Code-Fixing" accesskey="p" rel="previous">Code Fixing</a>, Up: <a href="Tools.html#Tools" accesskey="u" rel="up">Tools</a> &nbsp; [<a href="Index-table.html#Index-table" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Documentation-Generation-1"></a>
<h3 class="section">13.5 Documentation Generation</h3>
<a name="index-documentation-generation"></a>

<p>GPS provides a documentation generator which processes source files
and generates annotated HTML files.
</p>
<p>It is based on the source cross-reference information (e.g. generated by
GNAT for Ada files). This means that you should ensure that cross-reference
information has been generated before generating the documentation.
It also relies on standard comments that it extracts from the source code.
Note that unlike other similar tools, no macro needs to be put in your
comments. The engine in charge of extracting them coupled with the
cross-reference engine gives GPS all the flexibility needed to generate
accurate documentation.
</p>
<p>The documentation is put by default into a directory called <samp>doc</samp>, created
under the object directory of the root project loaded in GPS. If no such object
directory exists, then it is directly created in the same directory as the root
project. This behavior can be modified by specifying the attribute
Documentation_Dir in the package IDE of your root project:
</p><div class="smallexample">
<pre class="smallexample">project P is
   package IDE is
      for Documentation_Dir use &quot;html&quot;;
   end IDE;
end P;
</pre></div>

<p>Once the documentation is generated, the main documentation file is loaded
in your default browser.
</p>
<p>The documentation generator uses a set of templates files to control the final
rendering. This means that you can control precisely the rendering of the
generated documentation. The templates used for generating the documentation
can be found under <samp>&lt;install_dir&gt;/share/gps/docgen2</samp>. If you need a
different layout as the proposed one, you can change directly those files.
</p>
<p>In addition, user-defined structured comments can be used to improve the
generated documentation. The structured comments use xml-like tags. To define
your own set of tags, please refer to the GPS python extension documentation
(from GPS Help menu, choose &rsquo;Python extensions&rsquo;).
</p>
<p>The string values inside those tags are handled very roughly the same way as in
regular xml: duplicated spaces and line returns are ignored. One exception is
that the layout is preserved in the following cases:
</p><dl compact="compact">
<dt><code>The line starts with &quot;- &quot; or &quot;* &quot;</code></dt>
<dd><p>In this case, GPS makes sure that a proper line return precedes the line. This
is to allow lists in comments
</p></dd>
<dt><code>The line starts with a capital letter</code></dt>
<dd><p>GPS then supposes that the preceding line return was intended, so it is kept
</p></dd>
</dl>

<p>Some default tags have been already defined by GPS in
<samp>&lt;install_dir&gt;/share/gps/plug-ins/docgen_base_tags.py</samp>. The tags handled
are:
</p>
<dl compact="compact">
<dt><code>summary</code></dt>
<dd><p>Short summary of what a package or method is doing.
</p></dd>
<dt><code>description</code></dt>
<dd><p>Full description of what a package or method is doing.
</p></dd>
<dt><code>parameter (attribute &quot;name&quot; is expected)</code></dt>
<dd><p>Description of the parameter named &quot;name&quot;.
</p></dd>
<dt><code>exception</code></dt>
<dd><p>Description of possible exceptions raised by the method.
</p></dd>
<dt><code>seealso</code></dt>
<dd><p>Reference to another package, method, type, etc.
</p></dd>
<dt><code>c_version</code></dt>
<dd><p>For bindings, the version of the C file.
</p></dd>
<dt><code>group</code></dt>
<dd><p>For packages, this builds an index of all packages in the project grouped by
categories.
</p></dd>
<dt><code>code</code></dt>
<dd><p>When the layout of the value of the node needs to be preserved. The text is
displayed using a fixed font (monospace).
</p></dd>
</dl>

<p>The following sample shows how those tags are translated:
</p><div class="smallexample">
<pre class="smallexample">--  &lt;description&gt;
--    This is the main description for this package. It can contain a complete
--    description with some xml characters as &lt; or &gt;.
--  &lt;/description&gt;
--  &lt;group&gt;Group1&lt;/group&gt;
--  &lt;c_version&gt;1.0.0&lt;/c_version&gt;
package Pkg is

   procedure Test (Param : Integer);
   --  &lt;summary&gt;Test procedure with a single parameter&lt;/summary&gt;
   --  &lt;parameter name=&quot;Param&quot;&gt;An Integer&lt;/parameter&gt;
   --  &lt;exception&gt;No exception&lt;/exception&gt;
   --  &lt;seealso&gt;Test2&lt;/seealso&gt;

   procedure Test2 (Param1 : Integer; Param2 : Natural);
   --  &lt;summary&gt;Test procedure with two parameters&lt;/summary&gt;
   --  &lt;parameter name=&quot;Param1&quot;&gt;An Integer&lt;/parameter&gt;
   --  &lt;parameter name=&quot;Param2&quot;&gt;A Natural&lt;/parameter&gt;
   --  &lt;exception&gt;System.Assertions.Assert_Failure if Param1 &lt; 0&lt;/exception&gt;
   --  &lt;seealso&gt;Test&lt;/seealso&gt;

end Pkg;
</pre></div>

<p>Its documentation will be:
</p>

<a name="index-screen-shot-47"></a>
<img src="docgen.jpg" alt="docgen">


<p>The documentation generator can be invoked from two places inside GPS:
</p>
<dl compact="compact">
<dt><b><a href="The-Tools-Menu.html#The-Tools-Menu">The Tools Menu</a></b></dt>
<dd>
<dl compact="compact">
<dt><code>Generate project</code></dt>
<dd><p>Generate documentation for all files from the loaded project.
</p>
</dd>
<dt><code>Generate projects &amp; subprojects</code></dt>
<dd><p>Generate documentation for all files from the loaded project as well all
its subprojects.
</p>
</dd>
<dt><code>Generate current file</code></dt>
<dd><p>Generate documentation for the file you are currently editing.
</p>
</dd>
<dt><code>Generate for...</code></dt>
<dd><p>This will open a File Selector Dialog (see <a href="The-File-Selector.html#The-File-Selector">The File Selector</a>) and
documentation will be generated for the file you select.
</p>
</dd>
</dl>

</dd>
<dt><b>The Contextual Menu</b></dt>
<dd>
<p>When relevant (depending on the context), right-clicking with your mouse
will show a <code>Documentation</code> contextual menu.
</p>
<p>From a source file contextual menu, you have one option called
<code>Generate for &lt;filename&gt;</code>, that will generate documentation
for this file and if needed its corresponding body
(see <a href="The-Preferences-Dialog.html#The-Preferences-Dialog">The Preferences Dialog</a>).
</p>
<p>From a project contextual menu (see <a href="The-Project-View.html#The-Project-View">The Project View</a>), you will have the
choice between generating documentation for all files from the selected project
only or from the selected project recursively.
</p>
<p>You will find the list of all documentation options in
<a href="The-Preferences-Dialog.html#The-Preferences-Dialog">The Preferences Dialog</a>.
</p>
<p>Note that the documentation generator relies on the ALI files created by
GNAT. Depending on the version of GNAT used, the following restrictions may
or may not apply:
</p>
<ul>
<li> A type named <i>type</i> may be generated in the type index.

</li><li> Parameters and objects of private generic types may be considered as
types.
</li></ul>
</dd>
</dl>

<hr>
<div class="header">
<p>
Next: <a href="Metrics.html#Metrics" accesskey="n" rel="next">Metrics</a>, Previous: <a href="Code-Fixing.html#Code-Fixing" accesskey="p" rel="previous">Code Fixing</a>, Up: <a href="Tools.html#Tools" accesskey="u" rel="up">Tools</a> &nbsp; [<a href="Index-table.html#Index-table" title="Index" rel="index">Index</a>]</p>
</div>



</body>
</html>
gnat-gps-doc 5.0-16 / usr / share / doc / gnat-gps / html / Documentation-Generation.html
