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
Excluding entities¶
The tag @private notifies GNATdoc that no documentation must be generated on a given entity. For example:
type Calculator is tagged ...
procedure Add (Obj : Calculator; Value : Natural);
-- Addition of a value to the previus result
-- @param Obj The actual calculator
-- @param Value The added value
procedure Dump_State (Obj : Calculator);
-- @private No information is generated in the output about this
-- primitive because it is internally used for debugging.
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.