f90doc Documentation

See also the main page on f90doc.

Table of Contents


Comments in Code

f90doc recognizes all comments prefixed with !!. You can place a block of comments before a statement to be commented, or after the statement itself. For example:
    !! Support for variable-length strings.
    module string
is equivalent to
    module string     !! Support for variable-length strings.
but not
    module string;    !! Support for variable-length strings.
because here the comment is on a different statement than module string.

You can use free-form continuations to have a multi-line comment block the same statement as the one to be commented. For example:

    module string   & !! Support for variable-length strings.
                    & !! @version 1.0
                      !! @author Joe Bloggs
This doesn't make much sense for modules, but I find it useful for commenting variables. The before-statement version is:
    !! Support for variable-length strings.
    !! @version 1.0
    !! @author Joe Bloggs
    module string
You can even use a mix, which may be useful for certain applications:
    !! Support for variable-length strings.
    !! @author Joe Bloggs
    module string     !! @version 1.0

Comment Format

A particular constraint was that the comments in the code should look good in a text editor, while formatting reasonably well in a web browser or printed document. Hence, the two extremes of comments written in HTML and preformatted text are unacceptable (they are, however, supported).

Instead, there is a ``smart'' form for documentation. One or more blank lines (each optionally prefixed with !!) indicate a paragraph break. Lines of text are prefixed by !!, as already indicated. Line breaks in the comments do not cause line breaks in the generated output.

A line can be treated as verbatim text by putting a v immediately after the !!. The v is treated as a space, but otherwise no processing is performed on the line. There is a multiline verbatim mode using !!> (begin) and !!< (end). (The characters < and > are intended to be v's turned on their side.) Again, the < and > characters are treated as spaces, which means the following has uniform indentation:

    !! An example of this module's usage is
    !!>    call copier_read ("input_file")
    !!     call copier_write ("output_file")
    !!<    call copier_close
The most interesting feature is the list mode. This was designed to look like how people (or myself at least) do ASCII lists. An element of a list is marked with a dash - after an arbitrary number of spaces. All lists at this level must have the dash at the same indentation. Dashes with more indentation denote nested lists. Text at the same or lesser indentation than the last dash denotes the end of a list. For example:
    !! Mouths are defined by the following operations:
    !!     - Eat, which can be performed in two modes,
    !!         - open-mouth or
    !!         - closed-mouth.
    !!       The latter mode is preferred.
    !!     - Chew
    !! There are more operations, but this serves as an example.
This text is formatted in HTML as:
Mouths are defined by the following operations: There are more operations, but this serves as an example.
Note that verbatim text is treated as being part of the previous item.

Finally, there are two type-face modifiers, italics and bold (also known as emphasis and strong, respectively). Italic mode is started with an underbar _ at the beginning of a word, and ended with an underbar at the end of a word. For example, _big_ generates big. Underbars within italic text are replaced by spaces, so _really big_ and _really_big_ both produce really big. (Note: italicizing the word ``big'' is not encouraged!)

Similarly, bold mode has the same semantics but uses the character * instead of _. Note that multiple lines of either mode is currently not supported.

Macros

There are three simple macros currently supported.
@author A. Person
Adds A. Person to the list of authors. Only one author should be provided per @author statement. They are all collected and placed at the end of the comment block.
@version 1.2.3q
Sets the version number to 1.2.3q. There should only be one @version statement per comment block. It is displayed at the end of the comment block, after the authors.
@see ModuleName
Adds ``see also'' reference to another module. In the future, this will support referencing objects within modules.

Usage

The f90doc program itself is very easy to use. The main option is -c(p|s|h), described at the bottom. After that, you can specify a list of Fortran 90 files (e.g., *.f90 if that's expanded by your shell).

You can specify -fixed or -free before a group of Fortran files to specify whether to use fixed or free form. The default is free form.

Before a Fortran 90 file, you can use -o file.html to specify the output HTML document, affecting only the next source file. By default, the HTML documents will be generated in the current directory, and have the names of the corresponding top-level modules, subroutines, functions, or programs. An unnamed program will be written to program.html by default.

The -c option specifies the format of the !! comments in the files to be processed. -cp specifies that comments should be treated as verbatim (preformatted) text. This always works. -cs specifies that comments should be formatted ``smartly.'' This is the recommended option, and is the default. Finally, -ch specifies that comments are written in HTML, like JavaSoft's javadoc.

Internal options

f90doc has a few easy-to-tweak options. In particular, in htmling.pl, under "PUBLIC GLOBALS" you can find Unfortunately not much of f90doc is documented currently, so it is difficult to change much else unless you have a high familiarity with Perl and some time on your hands. Feel free to ask me questions about internal workings, and I'll reply as time allows and if I remember :-).

At some point I will get around to cleaning up f90doc in major ways, e.g., making it object-oriented, possibly switching to Python, adding real cross-module linking support, etc. But don't hold your breath. However, I will try to add features (again as time permits) if people make specific requests.

Last updated November 28, 2010 by Erik Demaine.Accessibility