[Ed: This post is about real work, not just my regular mumblings.]

I was delighted to find that doxygen, one of the world’s best code documentation tools, now supports Fortran 90.1 This now means that a very large body of scientific code out there can now be documented with the same awesome tools as many excellent codes out there, e.g. VTK.

I checked out doxygen version 1.5.5 and managed to get it to work on our lab group’s codebase: about 27,000 lines of Fortran with some Python glue.

Fortran support is clearly preliminary - the documentation doesn’t specify the syntax, and it took reading the lexer grammar file and some trial-and-error to figure it out, but it was worth it in the end.

If anyone out there is interested, here’s the summary of what I’ve found out:

Getting doxygen 1.5.5 to work with fortran code

  1. Patch the 1.5.5 release source code as described here to avoid crazy parsers errors with multi-line loops and if statements and things like that.
  2. If you’ve named your Fortran source files with coco with the .coco extension, or interface files with the .int extenstion, add these lines to initDoxygen() (near line 8930) in doxygen.cpp: 
    Doxygen::parserManager->registerParser(".int",   new FortranLanguageScanner);
Doxygen::parserManager->registerParser(".coco",   new FortranLanguageScanner);
  3. Compile, install, etc.
  4. Document the files like this for multiline headers 
    !> A constant function
!!
!<

function f(x)
x = 1
end function
  5. One-line documentation looks like this: 
          real (kind=8) :: pi = 3.1415926d0 !< A good enough approximation
  6. In Doxyfile, add *.int (and possibly *.coco) to FILE_PATTERNS for interface files and coco.

Stuff that still doesn’t work

  1. The doxygen parser sporadically chokes on files with multiple comment indicators. In Fortran, lines beginning with ‘*’, ‘c’ or ‘!’ are all considered valid comments. However, if more than one of these characters are used in the same file, the parser sometimes dies with the error message “Error: EOF reached in wrong state (end missing)”. I haven’t figured out why this happens, but in all the cases where this error occurred, I managed to fix it by standardizing all comments to ‘!’. However, there are some files with mixed comment indicators that parse fine. Go figure.
  2. Doxygen does not correctly process function or subroutine headers with continuation symbols, e.g. 
          function f ( real x,
     & real y)

    or

          function f ( real x, real
     & y)

    It will think there is a symbol called real& or &y something like that and throw an ‘unknown variable’ warning.

  3. Doxygen sometimes gives “Found unknown command: \todo” or “Found unknown command: @todo” warnings in documentation blocks with the \todo command. I think the syntax is correct though, and it doesn’t happen all the time.
  4. Doxygen appears to not recognize out-of-place documentation blocks for variables, e.g. 
    !>
!!    \var int f
!!    f is zero.
!<
      int f = 0
  5. With code like this, doxygen gives a “member with no name found” warning. I’m not sure if this is because I have the wrong syntax.
  6. Doxygen does not respect the case-insensitive nature of Fortran, e.g. 
    !>
!!    \param x argument of function
!<

      function f(X)
      real x

    With this code, doxygen returns a “argument `x’ of command \param is not found in the argument list of f(X)” warning.

  7. I can’t get multi-line in-code documentation blocks to work, e.g. 
          int x !< a
            !< variable

It would also be great if doxygen did some other things, like recognizing parameters to data type declarations (e.g. optional, parameter, intent(inout), allocatable), but overall I’m just happy right now to be able to use doxygen for my Fortran code.

Footnotes
  1. Some of you will doubtless say - what? you’re still using Fortran!? but it’s the de facto standard in the scientific computing world. For many reasons - a large existing codebase and the incredible pain in interfacing Fortran and C code being the top two - Fortran is still alive and kicking.↩