Some ideas for documenting Fortran procedures in (GitHub-Flavored) Markdown documents

template_ideas.md

Ideas for Fortran documentation in Markdown

Version 1 (f90doc-inspired)

Pros:

• Terse, reuses actual procedure declaration
• All argument attributes are visible

Cons:

• Not clear how to deal with interfaces and generic procedures for multiple kinds
• Not clear where to add description of arguments (declaration or under the long description)

---

procedure - single-line description

subroutine procedure(arg1,arg2)
  real(kind=[sp,dp]), intent(in) :: arg1
  real(kind=[sp,dp]), intent(inout) :: arg2
end subroutine

Procedure using two arguments arg1 and arg2.

Usage example:

call procedure(arg1,arg2)

---

Version 2 (gfortran-like)

Pros:

• Established look and feeling
• Clean categorization of information

Cons:

• Requires lots of vertical space
• Table is kind of hacky, due to Markdown constraints
• Missing variations for derived types and type-bound methods
• Argument attributes are not immediately visible

Variations:

• Use sixth header level (######) instead of italic formating for the items

---

procedure - Single-line description

Description:

Long description goes here.

Class:

impure subroutine

Syntax:

call procedure(arg1, arg2)

Arguments:

arg1	in	Argument 1 description
arg2	inout	Argument 2 description

---

Version 3 (FORD-inspired)

Pros:

• Clean argument table

Cons:

• More painful table preparation
• Doesn't look nice for procedures with long names, multiple arguments, and/or long argument names

---

procedure - Short description

subroutine procedure(arg1,arg2,longArgumentName,anotherLongArgumentName,aThirdLongArgument)

Name	Type & Attributes	Description
arg1	real, intent(in)	Argument 1 description
arg2	real, intent(inout), optional	Argument 2 description
longArgumentName	integer, intent(inout), optional	Argument 3 description
anotherLongArgumentName	character(len=*), intent(inout), optional	Argument 4 description
aThirdLongArgument	intent(inout), optional	Argument 5 description

Long description comes here

Usage example:

call procedure(arg1=abc,arg2=42.)

---

Version 4 (numpy-inspired)

Pros:

• Allows adding comments in-between

Cons:

• Uses a lot of vertical space
• Complex to prepare by hand

---

procedure(arg1,arg2)

Short description.

Interface

subroutine procedure(arg1,arg2)
real, intent(in) :: arg1
real, intent(inout), optional :: arg2
end subroutine

Parameters

• arg1 : A value
• arg2 : Another value. If not present, value is 42.

Notes

Long descriptions comes here.

See also

• More information can be found somewhere
• Even more information available elsewhere

Examples

This examples shows how to call the procedure

call procedure(a,b)