GENIE Using NaturalDocs

Intro

NaturalDocs (http://www.naturaldocs.org/) is a very useful package that turns fairl ordinary code comments into professional looking HTML documentation. In GENIE, if you type make doc, NaturalDocs will scan the whole repository for suitable comments and create a set of documenting HTML pages. See genie-main/doc/index.html for the result.

Rest assured, NaturalDocs will not, I'll repeat that, will not darg every murky comment out into the lime light. Your comments need to be of a particular format. Happily, this format is far from onerous and is, in fact, very natural (hence the name). The section below shows just how easy using NaturalDocs can be.

Quickstart

Here is a quick and simple example showing how you immediately get going using NaturalDocs:

MODULE mymodule

  ! File: mymodule.f90
  !
  ! Description:
  !
  ! A module containing some pretty useful stuff for use with widgets.

  ! var: koverall
  ! An important variable that I would like to document.

  integer :: koverall 

  contains:

    !  Subroutine: Multiply
    !
    !  Multiplies two integers.
    !
    !  Input:
    !
    !    x - The first integer.
    !    y - The second integer.
    !  
    ! Input/Output:   
    !
    ! Output:
    !
    !    z - The integer which results from the multiplication. 

    subroutine Multiply (x, y, z)

      integer, intent(in)  :: x
      integer, intent(in)  :: y
      integer, intent(out) :: z
 
      z = x * y

    end subroutine
end MODULE

To learn more about making your comments compatible, go to http://www.naturaldocs.org/documenting.html, especially the page showing which keywords you can use, http://www.naturaldocs.org/keywords.html.