13.5 Documentation Generation

GPS provides a documentation generator which processes source files and generates annotated HTML files.

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.

The documentation is put by default into a directory called doc, 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:

     project P is
        package IDE is
           for Documentation_Dir use "html";
        end IDE;
     end P;

Once the documentation is generated, the main documentation file is loaded in your default browser.

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 <install_dir>/share/gps/docgen2. If you need a different layout as the proposed one, you can change directly those files.

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 'Python extensions').

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:

The line starts with "- " or "* "

In this case, GPS makes sure that a proper line return precedes the line. This is to allow lists in comments

The line starts with a capital letter

GPS then supposes that the preceding line return was intended, so it is kept

Some default tags have been already defined by GPS in <install_dir>/share/gps/plug-ins/docgen_base_tags.py. The tags handled are:

summary

Short summary of what a package or method is doing.

description

Full description of what a package or method is doing.

parameter (attribute "name" is expected)

Description of the parameter named "name".

exception

Description of possible exceptions raised by the method.

seealso

Reference to another package, method, type, etc.

c_version

For bindings, the version of the C file.

group

For packages, this builds an index of all packages in the project grouped by categories.

code

When the layout of the value of the node needs to be preserved. The text is displayed using a fixed font (monospace).

The following sample shows how those tags are translated:

     --  <description>
     --    This is the main description for this package. It can contain a complete
     --    description with some xml characters as < or >.
     --  </description>
     --  <group>Group1</group>
     --  <c_version>1.0.0</c_version>
     package Pkg is
     
        procedure Test (Param : Integer);
        --  <summary>Test procedure with a single parameter</summary>
        --  <parameter name="Param">An Integer</parameter>
        --  <exception>No exception</exception>
        --  <seealso>Test2</seealso>
     
        procedure Test2 (Param1 : Integer; Param2 : Natural);
        --  <summary>Test procedure with two parameters</summary>
        --  <parameter name="Param1">An Integer</parameter>
        --  <parameter name="Param2">A Natural</parameter>
        --  <exception>System.Assertions.Assert_Failure if Param1 < 0</exception>
        --  <seealso>Test</seealso>
     
     end Pkg;

Its documentation will be:

The documentation generator can be invoked from the Tools->Documentation menu:

Generate project

Generate documentation for all files from the loaded project.

Generate projects & subprojects

Generate documentation for all files from the loaded project as well all its subprojects.

Generate current file

Generate documentation for the file you are currently editing.

Generate for...

This will open a File Selector Dialog (see The File Selector) and documentation will be generated for the file you select.

In addition, when relevant (depending on the context), right-clicking with your mouse will show a Documentation contextual menu.

From a source file contextual menu, you have one option called Generate for <filename>, that will generate documentation for this file and if needed its corresponding body (see The Preferences Dialog).

From a project contextual menu (see The Project View), you will have the choice between generating documentation for all files from the selected project only or from the selected project recursively.

You will find the list of all documentation options in The Preferences Dialog.

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:

• A type named type may be generated in the type index.
• Parameters and objects of private generic types may be considered as types.