GENIE Using NaturalDocs

Intro

NaturalDocs (http://www.naturaldocs.org/) is a very useful package that turns 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 do the do. See genie-main/doc/index.html for the result.

Rest assured, NaturalDocs will not, I'll repeat that, will not drag every murky comment you make kiccking and screaming out into the lime light. Your comments need to be in a particular format. Happily, this format is far from onerous and is, in fact, very natural (your saying "ah" about now..). 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.