Known limitations

This page collects the behaviours of the current version that differ from what one may expect. Each was reproduced on small test sources. When a workaround exists it is given.

Comments

Comments before the entity are ignored, and !> / !! are not markers

The description is read from the lines after the opening statement. Doxygen-style markers are copied verbatim (!> text gives > text). See Formatting Fortran (.f90) Code for Auto-Documentation.

A use or implicit none before the description hides it

The comment must be the first thing after the signature.

$1, $2 positional descriptions do not work

The parser has support for lines such as $2: description in the header comment of a routine, but the pattern does not match a line beginning with $. Use the name of the argument.

A header line beginning with an argument name is taken as its description

x is scaled in place sets the description of x and stays in the text. Start sentences with another word.

Variable descriptions are single-line

The continuation lines of a variable are joined without any separator (add a trailing space), a bare ! ends the description, and a variable cannot hold a literal block or several paragraphs. Only the first :Label var:`value` line of a variable is kept.

Doubled :Default:

A variable with an initialiser and a :Default var:`...` line in its comment shows two :Default: fields. Keep one.

Declarations

Derived types

type :: name, type, public :: name and type, extends(...) :: name are listed without description and without component descriptions. Use type name. In a module made private by a private statement, the public :: name statement of a type must follow the definition. Type-bound procedures are not documented.

Kinds are not shown

real(8), real(kind=dp) and real(c_double) are all displayed as real (character lengths are kept).

Optional flag of dimension arguments

An argument used only to dimension an optional array may be reported as optional (see Examples).

Preprocessing

#ifdef and #if are not evaluated. The code of every branch is read: the modules used in several branches are all listed (this is why mpi and sf_mpi both appear for ed_read_input).

Order

Module variables are listed alphabetically (and the variables of derived types in declaration order); routines follow the order of the source in the module.

Case

All names are lower-cased by the parser. Use lower-case names in the directives (f:automodule:: sf_arrays) and roles.

Directives and options

:include-private: does nothing

Use :forceadd-members: (names of private members to document) or :members:.

:undoc-members: excludes

It is the list of members to hide, the reverse of the Python autodoc option of the same name. Undocumented members are always displayed. It overrides :members:.

:hide-output: needs a value

Write :hide-output: 1. A bare option is ignored.

:subsection_type: accepts rubric and title only

The value section is treated as rubric.

:indent:

Only tab and space. Set the width once with fortran_indent.

f:autointerface

Currently returns the argument list only, not the full description. Use f:autoroutine with the name of the interface: it produces the f:interface block with the arguments merged from the specific procedures.

f:autosrcfile and capital letters

The name is lower-cased before it is compared with the base name of the file: files with capitals in their name (SF_ARRAYS.f90) are never found. Use f:automodule.

f:autosrcfile :objtype:

Takes a single value.

Object directives take no options

f:autoroutine, f:autotype, f:autovariable, f:autoprogram and the other object directives do not accept :noindex: or any other option.

Unknown object names

The warning Wrong routine name: ... is followed by a Python KeyError that stops the directive. Check the name (and its case).

Configuration values that are not read

fortran_encoding and fortran_subsection_type are declared but currently ignored.

Domain

Signatures with result(...) or a leading type are not parsed

.. f:function:: f(x) result(y) and .. f:function:: real function f(x) are displayed as raw text; the object has no index entry and cannot be referenced. Write f(x) and describe the result in a :r field.

:r needs a name

:returns: text without a name raises an IndexError. Write :r real y: text.

Types and attributes containing spaces

In a :p field, real, dimension(:,:) A and x [intent(in), optional] are mis-analysed. Use :type A: ... or attributes without inner parentheses or spaces.

f:currentmodule

The argument is ignored and the current module is always reset to nothing. After an f:auto* object directive, the objects that follow are therefore not linked to a module.

f:module has no content

Text has to follow, not be indented under the directive.

Ambiguous names

A message more than one target found is printed and the first match is used. Use module/name or preferred-crossrefs.

Incremental builds

Fortran files are not dependencies of the pages that document them; use sphinx-build -E or touch the .rst file after editing a source.

Unresolved names in comments

A role in a Fortran comment that points to something not documented in the project (for example :f:func:`parse_input_variable` in ED_INPUT_VARS, which belongs to SciFortran) is simply displayed as text, without a link. It only warns when nitpicky = True.