Currently Being Moderated

Using Doxygen with Fortran source code

VERSION 29
Created on: Jan 25, 2010 7:46 AM by crpearso - Last Modified:  Apr 11, 2015 10:34 PM by bvanaart

I. Introduction

This document describes how to generate documentation for Fortran source code using the Doxygen automated documentation tool.   The Doxygen tool will automatically pick up any updated documented code, and generate a completely updated documentation set for the latest version of the code.

II. Doxygen Tool Setup

Doxygen uses a configuration file to control its behavoir.   The configuration file contains entities called tags.   Provided in the table below is a list of tags and their settings used to generate the example Fortran source code documentation.

Doxygen Tag Name
Tag Setting
PROJECT_NAME  String Name     e.g., "Doxygen Fortran Example"
OUTPUT_DIRECTORY   <directory path you set to place Doxygen output>   e.g   Doxygen_examples
OPTIMIZE_FOR_FORTRAN   YES
INPUT  <directory path you set for all files Doxygen will use to produce the document> e.g., ~/DoxygenFortranEx
FILE_PATTERNS   *.txt *.f *.include
IMAGE_PATH   <your path to place images to include in the document>  e.g., images
GENERATE_HTML*   YES     (to generate navigable pages using a browser)

*

The documentation can be output as Latex, Doc, HTML, etc formatted documents.  In this example, HTML was used.   To generate Latex formatted documents, for example, set the tag GENERATE_LATEX to YES.   Otherwise set it to NO.

In addition to extracting the source code details, you can create and include an Introduction section for the document.   This is called a mainpage.

Below is an example of some text in a mainpage that you may follow to customize for your document:

      /**
@mainpage Document Title

@section Introduction
Write some introductory remarks in this section.  For example,

This document describes the source code for the XYZ model.

One can add diagrams to the document.  For example,
The following diagram shows the breakdown of the entire XYZ model.

@image html exampleImage.png

*/


Note the following:

1. Doxygen can search for the mainpage file too, and this name is made known to Doxygen using the FILE_PATTERNS tag.   In this case the mainpage file is called mainpage.txt  and so one pattern that needs to be included is   *.txt

2. The symbols /** and */  need to be the first and last entries of the mainpage file.

3. Notice the @ symbols.   These announce keywords to Doxygen.  Most of the body of this file is text you enter that may introduce the project, model or anything that the source code was written for.

@image   Notice the inclusion of the image file name, generated as a png-formatted image.

Again, you can also include images that exist in various formats such as png in any part of the document by using the @image keyword.

III. Placement of Doxygen Keywords in Fortran Source Code

There are many keywords that Doxygen uses to generate a rich custom documentation set for a particular code.   See the following link for more information http://www.doxygen.nl/articles.html , especially the Quick Reference guide.

Below is an example of a Fortran file with Doxygen keywords embedded in it.

!------------------------------------------------------------------------------
! NASA/GSFC, Software Integration & Visualization Office, Code 610.3
!------------------------------------------------------------------------------
!
! MODULE: Module Name
!
!> @author
!> Module Author Name and Affiliation
!
! DESCRIPTION:
!> Brief description of module.
!
! REVISION HISTORY:
! DD Mmm YYYY - Initial Version
! TODO_dd_mmm_yyyy - TODO_describe_appropriate_changes - TODO_name
!------------------------------------------------------------------------------

module MyModule_mod

use AnotherModule_mod

implicit none

public MyModule_type            ! TODO_brief_description

public someFunction             ! TODO_brief_description

! NOTE_avoid_public_variables_if_possible

contains

!---------------------------------------------------------------------------
!> @author
!> Routine Author Name and Affiliation.
!
! DESCRIPTION:
!> Brief description of routine.
!> @brief
!> Flow method (rate of change of position) used by integrator.
!> Compute \f$\frac{d\lambda}{dt} , \frac{d\phi}{dt}, \frac{dz}{dt} \f$
!
! REVISION HISTORY:
! TODO_dd_mmm_yyyy - TODO_describe_appropriate_changes - TODO_name
!
!> @param[in] inParam
!> @param[out] outParam
!> @return returnValue
!---------------------------------------------------------------------------

function someFunction
use AnotherModule

real, intent(in) :: inParam
real, intent(out) :: outParam
real, intent(inout) :: inOutParam   !TODO_description
real :: returnValue

real :: someVariable                !> @var Variable description

! TODO_insert_code_here

end function someFunction

end module MyModule_mod


Note the following contained in the above source code example:

\f$\frac{d\lambda}{dt} , \frac{d\phi}{dt}, \frac{dz}{dt} \f$

this shows how Doxygen allows you to include equations generated using Latex commands in the body of the source code.

IV. Generate Your Custom Doxygen Documention Set

Doxygen is installed on the Discover system under:
/usr/local/other/SLES11.3/doxygen/1.8.9.1/gcc-4.6.3-sp3/bin/

Once the Doxygen configuration file has been changed as described above, documentation can now be generated, just execute the following command:

doxygen <configuration file name>

To view the newly generated documentation,  change directory to the path name that the above Doxygen Tag Name OUTPUT_DIRECTORY was set to, and locate the appropriate documention file.  For example, in this document HTML-formatted documentation was created, so the index file will be in the directory <OUTPUT_DIRECTORY>/html  .

V. For Example

Included in this section is a specific example you can try.

- Untar the attached file DoxygenFortranExample.tar

-- The example output is in DoxygenFortranEx/Doxygen_examples/html

- Bring up a browser and open the file index.html

- If you want to generate the example yourself, execute doxygen in DoxygenFortranEx as follows:

doxygen DoxygenConfigFortran

Attachments: