Introduction

GNATdoc is a documentation tool for Ada which processes source files, extracts documentation directly from the sources, 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. The engine in charge of extracting them coupled with the cross-reference engine gives GNATdoc all the flexibility needed to generate accurate documentation, and report errors in case of wrong documentation.

Installation

GNATdoc is shipped as part of the GPS package. To install it, simply launch the GPS installer.

After the installation place <gps_installation_prefix>/bin/ in your PATH environment variable.

Launching GNATdoc

GNATdoc 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. For this purpose, before launching the tool compile your project.

GNATdoc requires your project hierarchy to be described via GNAT project files (.gpr).

To launch GNATdoc, execute:

gnatdoc -P<your_project>

where <your_project> is the .gpr file at the root of your project hierarchy (your root project).

GNATdoc generates an HTML report in the gnatdoc directory of the object directory of the main project.

Command line interface

A brief description of the supported switches is available through the switch –help:

$ gnatdoc --help
GNATdoc command line interface
Usage: gnatdoc [switches] [arguments]

-P, --project=ARG  Load the given project (mandatory)
-X ARG             Specify an external reference in the project
-R, --regexp=ARG   Regular expression to select documentation comments
-b                 Process bodies
--ignore-files=ARG List of files ignored by GNATdoc
-l                 Leading documentation
--no-subprojects   Do not process subprojects
-p                 Process private part of packages
-q                 Be quiet/terse
--single-file=ARG  Single file processed by GNATdoc
-w                 Enable warnings for missing documentation
--enable-build     Rebuild the project before processing it
--output=ARG       Format of generated documentation

Project (-P)

Specify the path name of the main project file. The space between -P and the project file name is optional.

External reference (-X)

Specify an external reference in the project.

Regular expression (-R)

Regular expression used to select comments containing documentation. If not specified then all the comments found in the specification of the compilation units of the project are used to document the project; if specified then only those comments matching the specified regular expression are used to generate the documentation.

For example, the regular expression “^-<” can be used to select the documentation of the following subprogram and skip the internal comment:

function Set_Alarm
  (Message : String;
   Minutes : Natural) return Boolean;
--- Display a message after the given time.
--  TODO: what is the unit for Minutes?
--- @return True iff the alarm was successfully registered

Process bodies (-b)

By default GNATdoc does not process the body of packages. This switch enables retrieving documentation of subprograms from the body of packages. GNATdoc first looks for the documentation in the package specification; if no documentation is found in the spec and this switch is enabled then searchs for the documentation in the body of the subprogram.

Ignore files (–ignore-files)

This switch allows to specify a list of source files ignored by GNATdoc. The names of the files can be separated by spaces or commas. For example:

gnatdoc -P default.gpr --ignore-files="file_1.ads,file_2.ads"
gnatdoc -P default.gpr --ignore-files="file_1.ads file_2.ads"

Leading documentation (-l)

By default GNATdoc extracts the documentation by first looking at the comments located after the entity declaration and fallback to the comments located before the entity if not found. This switch reverts such behavior, thus extracting first leading comments.

Do not process subprojects (–no-subprojects)

By default GNATdoc generates the documentation of all the files of a root project and its subprojects. This switch restricts the generation of documentation to the root project.

Process private part of packages (-p)

By default GNATdoc does not generate documentation for declarations found in the private part of packages. This switch enables the generation of such documentation.

Be quiet / terse (-q)

Do not display anything except errors.

Single file (–single-files)

By default GNATdoc generates the documentation of all the files of a project. This switch restricts the generation of documentation to the specified file.

Enable warnings for missing documentation (-w)

Emit warnings for fields, parameters or subprograms which do not have documentation.

Rebuild the project before processing it (–enable-build)

GNATdoc will launch gprbuild on the project before building the documentation.

Output format (–output)

At current stage GNATdoc generates HTML files (–output=html).

Annotating source files

GNATdoc extracts documentation directly from the comments present in source files for your project. Special tags present in the comments are interpreted by GNATdoc.

Documenting packages

The documentation attached to each package is the block of comment directly preceding the package declaration.

The following tags are supported in package comments:

@summary

a summary of the package

@description

a detailed description of the package

For example:

--  @summary
--  Drawing routines.
--
--  @description
--  This package provides routines for drawing basic shapes and Bézier curves.
--
package Drawing is

Documenting enumeration types

The documentation attached to each enumeration type is the block of comment directly following the record type declaration, or directly preceding it if the option -l was specified.

The following tag is supported when annotating enumeration literals:

@value

document an enumeration literal, with the following syntax:

@value <enumeration_literal> <description>

where:

<enumeration_literal>

is the value of the enumeration literal as it appears in the enumeration type declaration.

<description>

the documentation for the enumeration literal; all following text is considered for inclusion, until a blank comment line or another tag is encountered.

For example:

--  Colors supported by this drawing application
--  @value Black The black color is the default color of the pen
--  @value White The white color is the default color of the background
--  @value Green The green color is the default color of the border
type Colors is (Black, White, Green);

Enumeration literals can also be documented in line, with the documentation for each literal directly following its declaration (or directly preceding the component declaration, if the option -l was specified). In this case, the tag @value is not required:

--  Colors supported by this drawing application
type Colors is (
  Black,
  -- The black color is the default color of the pen
  White,
  -- The white color is the default color of the background
  Green
  -- The green color is the default color of the border
);

As shown above, a combined approach of documentation is also supported (see that the general description of the enumeration type Colors is located before its declaration and the documentation of its literals is located after their declaration).

Documenting record types

The documentation attached to each record type is the block of comment directly following the record type declaration, or directly preceding it if the option -l was specified.

The following tags are supported when annotating subprograms:

@field

document a record component, with the following syntax:

@field <component_name> <description>

where:

<component_name>

is the name of the component as it appears in the subprogram.

<description>

the documentation for the component; all following text is considered for inclusion, until a blank comment line or another tag is encountered.

For example:

--  A point representing a location in integer precision.
--  @field X Horizontal coordinate
--  @field Y Vertical coordinate
type Point is
 record
    X : Integer;
    Y : Integer;
 end record;

Record components can also be documented in line, with the documentation for each component directly following its declaration (or directly preceding the component declaration, if the option -l was specified). In this case, the tag @field is not required:

--  A point representing a location in integer precision.
type Point is
 record
    X : Integer;
    --  Horizontal coordinate
    Y : Integer;
    --  Vertical coordinate
 end record;

As shown above, a combined approach of documentation is also supported (see that the general description of the record type Point is located before its declaration and the documentation of its components X and Y is located after their declaration).

Documenting subprograms

The documentation attached to each subprogram is the block of comment directly following the subprogram declaration, or directly preceding it if the option -l was specified.

The following tags are supported when annotating subprograms:

@param

document a subprogram parameter, with the following syntax:

@param <param_name> <description>

where:

<param_name>

is the name of the parameter as it appears in the subprogram.

<description>

the documentation for the parameter; all following text is considered for inclusion, until a blank comment line or another tag is encountered.

@return

document the return type of a function, with the following syntax:

@return <description>

where:

<description>

is the documentation for the return value; all following text is considered for inclusion, until a blank comment line or another tag is encountered.

@exception

document an exception, with the following syntax:

@exception <exception_name> <description>

where:

<exception>

is the name of the exception potentially raised by the subprogram

<description>

is the documentation for this exception; all following text is considered for inclusion, until a blank comment line or another tag is encountered.

For example:

function Set_Alarm
  (Message : String;
   Minutes : Natural) return Boolean;
--  Display a message after the given time.
--  @param Message The text to display
--  @param Minutes The number of minutes to wait
--  @exception System.Assertions.Assert_Failure raised
--     if Minutes = 0 or Minutes > 300 if Minutes = 0
--  @return True iff the alarm was successfully registered

The parameters can also be documented in line, with the documentation for each parameter directly following the parameter type declaration (or directly preceding the parameter declaration, if the option -l was specified). In this case, the tag @param is not required:

function Set_Alarm
  (Message : String;
   --  The text to display

   Minutes : Natural
   --  The number of minutes to wait
  ) return Boolean;
--  Display a message after the given time.
--  @exception System.Assertions.Assert_Failure raised
--     if Minutes = 0 or Minutes > 300 if Minutes = 0
--  @return True iff the alarm was successfully registered

Adding images

Documentation for packages and subprograms may include images.

This is done via the attribute:

@image

where the first parameter is the name of an image file. This file is expected in the images directory, as specified in the project file: see section Images directory below.

Configuration

Output directory

The documentation is generated by default into a directory called gnatdoc, created under the object directory of the root project. This behavior can be modified by specifying the attribute Documentation_Dir in the package IDE of your root project:

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

Ignore subprojects

By default GNATdoc recursively processes all the projects on which your root project depends. This behavior can be modified by specifying the attribute Ignored_Subprojects in the package Documentation of your root project:

with "prj_1";
with "prj_2";
with "prj_3";
project Default is
   package Documentation is
      for Ignored_Subprojects use ("prj_1", "prj_3");
   end Documentation;
end Default;

Images directory

The directory containing images is specified by the string attribute Image_Dir of the Documentation package:

package Documentation is
   for Image_Dir use "image_files";
end Documentation;

Documentation pattern

The pattern for recognizing doc comments can be specified via the string attribute Doc_Pattern of the Documentation package:

package Documentation is
   for Doc_Pattern use "^<";
   --  This considers comments beginning with "--<" to be documentation
end Documentation;

If this attribute is not specified, all comments are considered to be doc.

This has the same semantics as the -R command-line switch. The command-line switch has precedence over the project attribute.

HTML templates

GNATdoc uses a set of templates files to control the final rendering. Modifying these templates you can control the rendering of the generated documentation. The templates used for generating the documentation can be found under <install_dir>/share/gps/gnatdoc. If you need a different layout as the proposed one, you can change directly those files.