Skip to content

MAPL Documentation Standards with FORD

Jump to bottom
JulesKouatchou edited this page Feb 10, 2023 · 8 revisions

Abstract

This report describes the standards we can follow to document the MAPL source code using FORD tags. In particular, we present where and how appropriate comments can be included to automatically generate documentations with FORD.

1 Introduction

Each software, whether created by a small group or by several teams, needs some related documentation. The documentation needs to explain why the software was designed, how it works, and how it is intended to be used. The main of purpose of software documentation is to streamline the communication between all the parties involved with the use of the software. TutorialPoints lists the advantages of software documentation:

  • Keeps track of all parts of a software or program
  • Maintenance is easier
  • Programmers other than the developer can understand all aspects of software
  • Improves overall quality of the software
  • Facilitate the software component reusability.
  • Aids in helping the end-users and assists in user training
  • Ensures knowledge de-centralization and knowledge capturing.

The challenge that we have is how do we produce such a documentation and update it specially while the software still evolves. We cannot properly describe what a dynamic software does if we cannot automatically generate from it useful information that can be included in the documentation. Software documentation is a critical process in the overall software development process. We need to establish standards and processes to write appropriate comments in the software that will be used to provide a comprehensive description of the software components.

Documenting scientific software has its own requirements [1][2][3]. One issue that arises is to define what good documentation actually involves, what it should contain and and how it should be done. Also, there is a need to clarify who has the responsibility to document the code, for whom, what, where, when and how. Any scientific software documentation needs to be at least usable, reliable and maintainable. In addition, it clearly describes how the software is used and its limitations.

In the case of MAPL, we want to have a documentation that is automatically derived from the source code with the objective of having up-to-date, consistent (a statement on an item made at one place in a document should not contradict the specification of the same item at another location), modifiable ( future changes do not destroy the structure of the document), traceable and accurate documentation as modifications are made in the code. We need to have the following requirements in terms of commenting out MAPL source code:

  • Comments attached to program units, variables and derived types may be automatically documented.
  • Documentation must precede the declaration of the unit, variable or derived type.
  • Comments shall be indented to align with the code.
  • Comments shall explain what a code does and why, not how it does it. The code needs to explain itself how it is done.
  • Documentation should be updated without disruption the software development process.
  • LaTeX style maths is used to include equations in the documentation.
  • Generate directory structure and call graphs.
  • Generate documentation that can be inspected without looking into the code (e.g. HTML-pages, PDF-document, etc.)
  • Generate searchable and browsable documentation.

We have decided to select FORD as the tool to document MAPL. In this document, we define simple and uniform standards for commenting out the code so that documentation takes place in everyday work and becomes part of the process in the development of MAPL. We want to make it easy to write the documentation at the same time as writing the code. In each program unit, we want to describe its intent, its input parameters, return values and usage examples (if possible).

2 Description of FORD

The goal of FORD is to be able to reliably produce documentation for modern Fortran software which is informative and nice to look at. The documentation should be easy to write and non-obtrusive within the code. While it will never be as feature-rich as Doxygen, hopefully FORD will be able to provide a good alternative for documenting Fortran projects.

FORD allows documentation to be placed in the README.md files as well as the source files. FORD processes markup describing classes, procedures, and variables in the header/source files and generates a user-friendly hyperlinked set of web pages. These web pages allow the user to navigate all the program units, classes, procedures, and variables and see 1) class hierarchy relationships; 2) input and output parameters for methods and procedures; and 3) other variables and associated data.

Here are the FORD capabilities:

  • An automatic documentation generator for modern (1990 onward) Fortran code.
  • Was created to fixed the limitation of Doxygen to handle new features of Fortran.
  • Able to extract information about variables, procedures (functions and subroutines), procedure arguments, derived types, programs, and modules from the source code.
  • Source code can also be preprocessed;.
  • Able to extract documentation from comments in the source code.
  • Uses Markdown to type-set documentation.
  • Able to use LaTeX (through \href{http://www.mathjax.org/}{MathJax})
  • Able to create a hierarchical set of pages containing general information, not associated with any particular part of the source code.
  • Able to include the contents of other files within the documentation.
  • Symbols (e.g. main code, modules, derived data types) are appropriately colored.
  • Provide links:
    • to download the source code.
    • to individual files, both in their raw form or in HTML with syntax highlighting.
    • between related parts of the software.
  • Use configurable settings to generate documentation. The settings allow users to define which types of comments can be used for documentation.
  • Can add GitHub (Bitbucket), Twitter and LinkedIn pages.
  • Searchable documentation using Tipue Search which supports a wide range of Web browsers. Can search source code as well as procedures, variables, comments, etc.

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.
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. Some non-Markdown syntax can also be used with FORD.

3 Templates

Special Fortran comments to be processed by FORD start with !> before any procedure, variable and program unit to be documented. Subsequent comments proceed ! until the last one is encountered. In addition, each variable is documented with !! on the same line the variable is declared and **!!** for continuation line.

>
! Compute the area of a triangle using the Heron's formula:
!
!$$
!\begin{equation}
!s  = \frac{a+b+c}{2}  \\\\
!A  = \sqrt{s(s-a)(s-b)(s-c)}
!\label{eq:tri}
!\end{equation}
!$$
!
   real function calc_area( a, b, c )
      ! This line will not be documented.
      real, intent(in)  :: a !! Opposite
                            !! More comments on the opposite.
      real, intent(in)  :: b !! Adjacent
      real, intent(in) :: c  !! Hypothenus
      real :: s
      s = (a + b + c) / 2.0
      calc_area = sqrt(s*(s-a)*(s-b)*(s-c))
   end function calc_area
   
!> 
! Compute the hypothenus of a right angle triangle.
! 
! The length of the hypotehnus is given by: 
! \( c = \sqrt{a^2 + b^2} \)
! 
! This is the last line of the commented section.
subroutine compute_hypothenus(a, b, c)
    real, intent(in)   :: a !! Base
    real, intent(in)   :: b !! Perpendicular
    real, intent(out) :: c  !! Hypothenus
    c = sqrt(a**2 + b**2)
end subroutine compute_hypothenus

References

[1] Benjamin D. Lee (2018) Ten simple rules for documenting scientific software, PLoS Comput Biol., 14(12): e1006561, https://doi.org/10.1038/s41598-022-10376-9.

[2] Sibylle Hermann and Jorg Fehr (2022) Documenting research software in engineering science, Sci Rep, 8, 6567, [https://doi.org/10.1371/journal.pcbi.1002802](https://doi.org/10.1371/journal.pcbi.1002802].

[3] W. Spencer Smith and Nirmitha Koothoor (2016) A Document-Driven Method for Certifying Scientific Computing Software for Use in Nuclear Safety Analysis, Nuclear Engineering and Technology, 48(2), p. 404-418, https://doi.org/10.1016/j.net.2015.11.008.

Clone this wiki locally