Automatic Documentation Generator for Source File

Help
1

I would like to hear what positive or negative reviews people can give for source file “automatic” documentation generators. What program do you recommend that I give a try. I see that there is FORD, Doxygen, Sphinx-Fortran, ROBODoc, Fortrandoc and others. There seem to be two categories of doc generators. Some just process special comments that are manually inserted, and some try to read the Fortran and make sense of it. Ideally I would like something that does a bit of both. I would like to find something out there that automatically produces a list of all routines, and for each routine lists what it calls and what calls it? Adding to the wish list, the doc generator would list out variables. Thank you for your suggestions!

1 Like
2

I’ve had good experiences with FORD. It’s the most robust of the existing tools. I’ve also had to work with Doxygen, but it takes more manual tinkering.

3

FORD is used for stdlib. See here the result of applying FORD on stdlib specs and source code. I prefer FORD output over Doxygen output.

4

Thank you for the recommendation to check out FORD.

5

Hi,

in the early days of our gtk-fortran project some documentation was automatically generated from source code comments, but the memory of which tool was exactly used is uncertain… This is the syntax that was used in the comments:

  • A block delimited by !* and !/ provides a section header.
  • A block delimited by !+ and !- describes an individual routine. The arguments are described in a colon-separated list with name: type : status : description.

See for example that file: https://github.com/vmagnin/gtk-fortran/blob/gtk4/src/gtk-hl-container.f90
And an example of a generated documentation: https://github.com/vmagnin/gtk-fortran/wiki/Highlevel-api

Do you think the tool could be Doxygen ? I tried to used Doxygen but didn’t succeeded to obtain something from those blocks.

Do you think FORD could be configured to use these block syntaxes?

6

@vmagnin By defauld FORD interprets comments starting with !! and that come after what it should be documented as documentation (as well as comments starting with !> that are placed before what should be documented).
However, both default marks (!! and !>) can be changed. You can find more details here.

1 Like