A presentation given on GNAT Pro User Day about GNATdoc, a GNAT Pro tool for automatic documentation generation.

2. GNATdoc
Automatic Documentation Generator
Presented by
Vasiliy Fofanov

3. “Automatic documentation”?
• Keeping source and documentation in sync by hand is hard
o Parameters added/removed …
o New subprograms, derived types …
o Description changes
o Maintaining cross-references between program entities is a nightmare
• Solution: generate docs directly from the source
o Specially placed/formatted comments used to supply additional information

4. GNATdoc Highlights
• Generates a “web site” from your source code
o Syntax highlighting
o Cross-references
o Multiple indexes
- Packages, entities, source files, inheritance tree…
o Extracts inline annotations from comments

5. GNATdoc Highlights #2
• Command line tool
• Project aware
o “Package documentation”
o As simple as “gnatdoc –P<your project>”
• Documentation patterns
• Customizable CSS
• GPS support (of course!)

6. Evolved from DOCGEN…
• Command-line tool, no longer GPS-only
• DOXYGEN/JAVADOC-like notation
o “@param” etc…
o Old DOCGEN notation is supported (but you can’t mix the two)
• Embedded comments don’t require annotation
o Supports both above- and below-the-source commenting styles

7. How it looks like…

8. Future directions
• Custom attributes with Python hooks
• GNATdashboard integration to allow decorating the documentation with
output from other tools
o Coverage info, …
• Support other output formats in addition to HTML
• We could potentially also support C/C++
o Let us know what you think … ;)

9. Conclusion
• GNATdoc is a very useful tool for quickly generating good-looking library
documentation
• We have started using it in-house for documenting our library products
o GtkAda…
Questions?