Fortran/Documenting Fortran

FORD - FORtran Documenter

edit

A great program for documenting fortran source code is FORD.

See the github page for instructions on installing, and usage of FORD: github.com.

Documenting Fortran using Doxygen

edit

Documentation can be created right from source code using Doxygen.

The commandline program doxygen creates the documentation using configuration files. The gui program doxygen-wizard helps creating those files.

Overview

edit

The source code needs to be documented using special comment syntax:  !>, and  !!.

One should always set OPTIMIZE_FOR_FORTRAN = YES within the configuration file.

Doxygen commands are usually ended by an empty comment line or a new doxygen command.

Note that support for Fortran is rather bad in doxygen. Even simple constructs such as public/private statements inside of types are not supported (see here github.com).

LaTeX

edit

One can also include LaTeX code within the documentation. Doxygen's website gives detailed information.

Examples

edit

subroutine

edit
!> @brief inserts a value into an ordered array
!!
!! An array "list" consisting of n ascending ordered values. The method insert a
!! "new_entry" into the array.
!! hint: use cshift and eo-shift
!!
!! @param[in,out]   list    a real array, size: max_size
!! @param[in]       n       current values in the array
!! @param[in]       max_size    size if the array
!! @param[in]       new_entry   the value to insert
subroutine insert(list, n, max_size, new_entry)
    implicit none
    real, dimension (:), intent (inout) :: list
    integer, intent (in) :: n, max_size
    real, intent (in) :: new_entry

    ! code ........
end subroutine insert

function

edit
!> @brief calcs the angle between two given vectors
!!
!! using the standard formula:
!!  \f$\cos \theta = \frac{ \vec v \cdot \vec w}{\abs{v}\abs{w}}\f$.
!!
!! @param[in]   \f$v,w\f$   real vectors
!! @return  a real value describing the angle. 0 if \f$\abs v\f$ or \f$\abs w\f$ below a
!!          threshold.
pure function calc_angle(v, w) result (theta)
  implicit none
  real, dimension (:), intent (in) :: v, w
  real :: theta

  ! code .......
end function calc_angle

Troubleshooting

edit

Empty documentation

edit

If the documentation is just an empty page then one can try setting EXTRACT_ALL = YES.