Automatically Generated Documentation

Html documentation is automatically generated from .F90 files in fluidity. The documentation is constructed using "make doc" and appears in the doc directory under the main fluidity source directory. A (hopefully recent) version of the documentation is [http://amcg.ese.ic.ac.uk/~dham/fluidity-doc available here].

Contents

The documentation contains all function and subroutine headers. Type definitions, interfaces and variables are shown if they are declared in the header of a module. Comments associated with these objects may be shown as indicated below.

Start by navigating from doc/index.html in the fluidity source directory. fetools.html and quadrature.html provide reasonable examples of what should happen.

Magic Comments

Some comments are extracted and placed in the documentation. A comment is extracted if:

• it begins with '!!' instead of just '!'; and
• it is a trailing comment for a line which is extracted to the documentation or it ''belongs'' to such a line.

The rules for ownership of comments by lines are:

• A line beginning '!! ' belongs to the following line.
• A line beginning '!!<' belongs to the previous line.

For example:

 function foo(bar) !! This comment belongs to the function declaration.
   !!< So does this one
   !! This comment belongs to implicit none so it won't show up in the docs.
   implicit none
   !! This comment belongs to the declaration of foo
   real :: foo
   !! This comment belongs to bar.
   ! This comment only has one leading ! so it will be ignored.
   real :: bar

Comment Formatting

Two simple comment formatting rules are applied. First, most comments are formatted as paragraphs. A blank line is a paragraph break.

If a comment begins with two spaces after the "!!" then the comment will be rendered as preformatted text.

Special comments

Comments of the form '!!@' are special instructions to the documentation system. At the moment, the only one supported is '!!@skip' which causes the documentation system to ignore the next line.

Limitations/To Do

• Most files don't have !! comments yet!
• More links in output. Eg. links to definitions of data types.
• Auto-generated names index.
• Parser is still dodgy on some code constructs.
• More formatting options for comments.
• Fixed form source support (blech!)