# Fortran/Documenting Fortran

## FORD - FORtran Documenter

editA 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

editDocumentation 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

editThe 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 `type`

s are not supported (see here github.com).

### LaTeX

editOne 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

editIf the documentation is just an empty page then one can try setting ` EXTRACT_ALL = YES`

.