Using Ford to document Fortran programs

Ford is a tool which can help document Fortran source code. Here we show how to use Ford and the value of automatic documentation generation.

It's important to document research software source code just as we (hopefully) provide a user guide or manual. We can write comments in our code which describe what a particular function or block of code is doing:

// In this function we take two double arguments and return their sum.
// The arguments are passed by value.
double my_adder(double a, double b) {
  return a+b;
}

When our program is written in C, C++, Matlab, Python and other "popular" languages we have a wide variety of tools which can be used to automatically create standalone readable documentation of the procedures within the source code. For example, with Doxygen we can create documents describing appropriately annotated source code for a variety of languages. Doxygen does support Fortran code to a certain level, and the annotations are quite natural.

In ITSR, however, to generate documentation for Fortran we prefer the Ford package. This works in a similar way, based on annotating entities in the source code. On processing a Fortran project with Ford a set of HTML documents are prepared which may be viewed in a browser.

For example, given the simple Fortran function

pure function my_adder(a, b)
  real, intent(in) :: a
  real, intent(in) :: b
  real my_adder
  my_adder = a+b
end function my_adder

we know certain properties of the function and its arguments. The function my_adder is a pure real function with two scalar real non-optional arguments, each of which is intent(in).

Our automatic documentation generator, on scanning the source file, also sees these things. Output from Ford describing this function looks like:

We can add comments to the source code to explain the purpose of the function, and how it uses its arguments. If we do that in a way that our tool understands then these comments make it to the produced documentation:

!> Return the sum of two real numbers, such as \(a+b\).
pure function my_adder(a, b)
  real, intent(in) :: a  !! First number to add
  real, intent(in) :: b  !! Second number to add
  real my_adder          !! Sum of the two numbers
  my_adder = a+b
end function my_adder

Ford documents this function with these additional comments:

The sentinels !> and !! indicate comments to be processed by Ford and a LaTeX formula may be marked by the form \(...\).

Ford additionally documents aspects of the structure of the program: modules; derived type definitions; procedure call trees; use of intrinsic modules. Comments in the appropriate form in the source may propagate to the prepared documentation.

Further guidance on using Ford may be found in the Ford wiki and ITSR provides an example project (QMUL users only).