Fortran/Documenting Fortran

From Wikibooks, open books for an open world
Jump to navigation Jump to search

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/privare 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.