f90doc Documentation

Table of Contents

• Comments in Code
• Comment Format
• Macros
• Usage
• Internal options

Comments in Code

    !! Support for variable-length strings.
    module string

    module string     !! Support for variable-length strings.

    module string;    !! Support for variable-length strings.

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

    !! Support for variable-length strings.
    !! @version 1.0
    !! @author Joe Bloggs
    module string

    !! Support for variable-length strings.
    !! @author Joe Bloggs
    module string     !! @version 1.0

Comment Format

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

    !! 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.

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.

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

@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

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

• $htmling::suppress_calls = 0;
  Changing this to 1 removes the list of routines called from each unit. This is for if you want backward compatibility.

• $htmling::calls_make_links = 0;
  If you set this to 1, the list of called routines makes links in the obvious way; i.e., a call to xyz will generate a link to xyz.html.

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.