GNATDoc

GNATDoc’s settings may be conveniently placed inside of a .gpr project file under the Documentation package and then invoked in the same way as gprbuild with a -Pproject.gpr flag.

package Documentation is
   for Documentation_Dir   use "docs";
   for Image_Dir           use "imgs";
   for Ignored_Subprojects use ("a_project", "another_project");
   for HTML_Custom_Dir     use "docs/templates"; -- For specifying custom HTML/CSS templates

   for Doc_Pattern use "^-"; -- Documentation comments will now be those starting with "---".
                             -- By default, all comments are considered for documentation.

   for Custom_Tags_Definition use "my_tags.py";     -- For creating custom tag parsers
end Documentation;

Values for documentation comments are set via @tags where the tag varies per entity. The style used matches the settings given above.

--- @summary
--- Summarise the contents of the package.
---
--- @description
--- A more detailed description of the package is placed here. For the markup, each description
--- is taken as all of the text following the tag until either another tag or a blank line is
--- encountered (similar to markdown).
package P is

   type Direction is (East, North, West, South);
   --- Compass directions with separated documentation comments
   --- @value East  In a rightwards direction
   --- @value North In a upwards direction
   --- @value West  In a leftwards direction
   --- @value South In a downwards direction

   type Quadrant is (
      Q1, --- Top-right
      Q2, --- Top-left
      Q3, --- Bottom-left
      Q4  --- Bottom-right
   );
   --- The four 2D quadrants

   type Point is record
      X: Float;
      Y: Float;
   end record;
   --- A 2D point floating-point components
   --- @field X The x-coordinated of the point
   --- @field Y The y-coordinated of the point

   type Integer_Point is record
      X: Integer; --- The x-coordinated of the point
      Y: Integer; --- The y-coordinated of the point
   end record;
   --- A 2D point with integer components

   function F(p1: in String; p2: in out Integer) return Float;
   --- Does something Funky.
   --- @param p1 What the string input is for
   --- @param p2 What the integer input is for
   --- @exception Might raise `Storage_Error` if it gets too funky.
   --- @return The funkiness level

   function Is_Valid(p: Point) return Boolean;
   --- @private This is for internal use so we don't want it added to the documentation.

Markup

Markup	Notation	Details
Lists	-, *	Bullets need to have the same indentation.
Code Blocks	3+ spaces
Images	@image <path>	The file <path> uses the Image_Dir attribute as a starting point (images/ by default).

Custom Templates

If the attribute HTML_Custom_Dir is specified then files in the static/ subdirectory will be copied into the final documentation directory. Three files in the templates/ subdirectory are used as the templates to generate the final documentation. See the files index.xhtml, class.xhtml and unit.xhtml in GNATDoc’s share/gnatdoc/html/template directory as the starting point.

Custom Tags

TODO