Writing Documentation

FORD usage is based on projects. A project is just whatever piece of software you want to document. Normally it would either be a program or a library. Each project will have its own Markdown file which contains a description of the project. For details on some of the non-Markdown syntax which can be used with FORD, see below. Various options can be specified in this file, such as where to look for your projects source files, where to output the documentation, and information about the author. See ./example-project-file.md for a sample project file.

Other documentation is placed within the code. This is described in more detail below.

Indicating Documentation

In modern (post 1990) Fortran, comments are indicated by an exclamation mark (!). FORD will ignore a normal comment like this. However, comments with two exclamation marks (!!) are interpreted as documentation and will be captured for inclusion in the output. If desired, the character(s) designating documentation can be changed. By default, FORD documentation comes after whatever it is that you are documenting, either at the end of the line or on a subsequent line. This was chosen because it was felt it is easier to make your documentation readable from within the source-code this way. This

subroutine feed_pets(cats, dogs, food, angry)
    !! Feeds your cats and dogs, if enough food is available. If not enough
    !! food is available, some of your pets will get angry.

    ! Arguments
    integer, intent(in)  :: cats
        !! The number of cats to keep track of.
    integer, intent(in)  :: dogs
        !! The number of dogs to keep track of.
    real, intent(inout)  :: food
        !! The ammount of pet food (in kilograms) which you have on hand.
    integer, intent(out) :: angry
	    !! The number of pets angry because they weren't fed.
		
    !...
    return
end subroutine feed_pets

looks better/more readable than

!! Feeds your cats and dogs, if enough food is available. If not enough
!! food is available, some of your pets will get angry.
subroutine feed_pets(cats, dogs, food, angry)

    ! Arguments
    !! The number of cats to keep track of.
    integer, intent(in)  :: cats
    !! The number of dogs to keep track of.
    integer, intent(in)  :: dogs
    !! The ammount of pet food (in kilograms) which you have on hand.
    real, intent(inout)  :: food
    !! The number of pets angry because they weren't fed.
    integer, intent(out) :: angry
		
    !...
    return
end subroutine feed_pets

in the opinion of this author, especially with regards to the list of arguments. Since version 1.0.0 it is now possible to place documentation before the code which it is documenting. To do so, specify in the meta-data of your project file predocmark: > (or whatever it is you want to use to indicate preceding documentation). In the first line of your preceding documentation, use !> rather than the usual !!. This can be used on all lines of the preceding documentation if desired, but this is not necessary.

Please note that legacy Fortran (fixed-form code) is not supported at this time. If anyone would like to contribute the necessary modifications to ./ford/reader.py to convert fixed-form syntax into free-form, it should not be difficult (see the approach taken by f90doc). However, it is not a priority for me right now (since I regard fixed-form Fortran as an abomination which should be wiped from the face of this Earth).

By default, FORD will preprocess any files in which all letters in the extension are capitalized, prior to parsing them for documentation. This behaviour can be disabled if desired. Note that any syntax-highlighted source code which is included in the documentation will be displayed in its non-preprocessed form.

Markdown

All documentation, both that provided within the source files and that given in the project file, should be written in Markdown. In addition to the standard Markdown syntax, you can use all of the features in Python's Markdown Extra. Other Markdown extensions automatically loaded are CodeHilite which will provide syntax highlighting for any code fragments you place in your documentation and Meta-Data. The latter is used internally as a way for the user to provide extra information to and/or customize the behaviour of FORD (see Documentation Meta-Data). Information on providing meta-data and what types of data FORD will look for can be found in the next section.

LateX Support

You can insert LaTeX into your documentation, which will be rendered by MathJax. Inline math is designated by \( … \), math displayed on its own line is indicated by $$ … $$ or \[ … \], and a numbered equation is designated by \begin{equation} … \end{equation}. Inline math will not be displayed with the traditional $ … $, as there is too much risk that dollar signs used elsewhere will be misinterpreted. You can refer back to number equations as you would in a LaTeX document. For more details on that feature, see the MathJax Documentation.

Special Environments

Much like in Doxygen, you can use a @note environment to place the succeeding documentation into a special boxed paragraph. This syntax may be used at any location in the documentation comment and it will include as the note's contents anything until the end of the paragraph. Other environments which behave the same way are @warning, @todo, and @bug. Note that these designations are case-insensitive (which, as Fortran programmers, we're all used to). If these environments are used within the first paragraph of something's documentation and you do not manually specify a summary, then the environment will be included in the summary of your documentation. If you do not want it included, just place the environment in a new paragraph of its own.

"Include" Capabilities

FORD uses my Markdown-Include extension. The syntax {!file-name.md!} in any of your documentation will be replaced by the contents of file-name.md. This will be the first thing done when processing Markdown, and thus all Markdown syntax within file-name.md will be processed correctly. You can nest these include statments as many times as you like. All file paths are evaluated relative to the directory containing the project file, unless set to do otherwise.

Macros

FORD features two macros to make it easier to provide intradocumentation links. These are |url| which gets replaced by the project URL, and |media|, which gets replaced by the (absolute) path to the media directory in the output.

Links

In addition to conventional Markdown links, FORD provides its own syntax for linking to other parts of the documentation. The general syntax for this is [[a(b):c(d)]] where the different letters represent:

• a is the name of the component of your project's code whose documentation is to be linked to. It could be a procedure, module, or anything else with its own page of documentation. This is the only item which is mandatory.
• b (optional) is a's type of Fortran construct. This is necessary if you have multiple items with the same name (such as a type and its public constructor). If multiple items with the same name exist and b is not specified then FORD's behaviour is undefined; it will link to the first of those items which it finds. The available options are "procedure", "subroutine", "function", "proc" (all of which are interchangeable and specify a procedure), "interface", "absinterface" (both of which are for abstract interfaces), and "type", "file", "module", and "program" (which are self-explanatory).
• c (optional) specifies an item within a which is to be linked to. The link's target will be c's location on a's page. If c is not present then the colon in the link must be omitted.
• d (optional, c must also be present) is c's type of Fortran construct. It can be used in the same manner as b, but has different options. These are "variable", "type", "constructor", "interface", "absinterface" (abstract interface), "subroutine", "function", "final" (finalization procedure), "bound" (type-bound procedure), "modproc" (module procedure in a generic interface block). None of these options are interchangeable. If no description is given then its meaning should be self-explanatory. If you specify an option that can not exist within a (for example, if a is a module and c is "bound") then a warning message is issued and the link is not generated.