version 0.5.0
How to correctly and nicely document your code

The following guidelines will help you use correctly inline comments to document your code.

As you may have noticed in Notus code, most of the modules and routines have a lot of comments above them. Every developer should spend some time to document his own code for future use and transmission to other developers. In the project, we use the Doxygen tool in order to generate pretty documentation (like this page) for the whole code.

The following guidelines will help you use correctly inline comments to document your code.

Warning
In this Howto, we give you particular commands that are interpreted by Doxygen. Because this documentation is itself interpreted by Doxygen, some commands were impossible to write as-is. Doxygen commands start with a @ followed by a keyword: in some cases, we have added a white space between the two but, in your document, you have to remove it! For example: @ section should, of course, have no white space between @ and section.

First step: generating the initial documentation

In your notus principal directory, open a terminal. To generate the HTML documentation associated to the code, simply type

doxygen doxygen.cfg

(of course, Doxygen has to be installed on your computer; if not, simply type sudo apt install doxygen in your terminal).

Wait a few seconds... or 1 minute if you possess one of those Flintstone's rocky machin. Once the tool has finished its job, simply open the file doc/html/index.html in your browser and welcome back!

Note
You will need to launch again the command doxygen doxygen.cfg every time you want to see the changes changes in your documentation!

Key concepts

Documenting your code is very easy: only a short number of commands are to remember! All the documentation resides in Fortran comments: every line starting with two !! will be interpreted as documentation...

Exception
When writing a new documentation block – for example for a subroutine or a module –, start the block with !> instead of !!! (see the example below).

Afterwards: simply type as it feels, your documentation will quickly look nice for everybody!

To make things even simpler: just copy/paste as-is this generic code above any subroutine, function or module... and voila!

!> @brief A short description of my subroutine (that can hold in one line)
!! @details
!! A long (multilines) description of my subroutine, how does it works,
!! what should I be aware of, LaTeX equations, etc.
!! @param[in] param1: the first (input) parameter
!! @param[inout] paramN: the Nth (input/output) parameter
!! @return what is the result of the function?

A simple example

To shown you how it works, look at this simple example:

!> @brief Solve the first order equation @f$ a x = b @f$
!! @details
!! This function solves the first order equation with very complex but efficient
!! numerical methods involving quantum calculus.
!! @param[in] a: the first known parameter @f$a@f$
!! @param[in] b: the second known parameter @f$b@f$
!! @result the numerical solution of the equation
function solve_first_order_equation( a, b ) result( x )
double precision, intent(in) :: a, b
double precision :: x
x = b / a
end function solve_first_order_equation

Look at what it looks like in your browser:

example1.png
A simple function documentation

pretty neat, isn't it?

A few more commands you should know

Now that you know the basic commands, you can be a bit more subtil and use several of those Doxygen commands to make things clearer (look at the lasts commands added):

!> @brief A short description of my subroutine (that can hold in one line)
!! @details
!! A long (multilines) description of my subroutine, how does it works,
!! what should I be aware of, LaTeX equations, etc.
!! @param[in] param1: the first (input) parameter
!! @param[inout] paramN: the Nth (input/output) parameter
!! @return What is the result of the function?
!! @pre Pre requirements of the subroutine (what should be true before entering)
!! @post Post assessment of the subroutine (what will be true after leaving)
!! @ex An **example** of usage
!! @warning A **warning** box will appear
!! @note A **note** box will appear
!! @todo a **todo** box will appear to remind everybody that nothing

A more detailed example

Adding a few more knowledge to the function, we can write this new documentation:

!> @brief Solve the first order equation @f$ a x = b @f$
!! @details
!! This function solves the first order equation with very complex but efficient
!! numerical methods involving quantum calculus.
!! @param[in] a: the first known parameter @f$a@f$
!! @param[in] b: the second known parameter @f$b@f$
!! @result the numerical solution of the equation
!! @pre @f$ a \ne 0 @f$
!! @warning For numerical reasons, to avoid division by zero,
!! there is a threshold on the nullity of a, ie. @f$ |a|<\text{threshold} @f$
!! @ex For @f$ a=2, b=40 @f$, the result will be @f$ x = 20 @f$
!! @note The use of a quantum calculus on a non quantum computer is of no harm
!! @todo It might be interesting to consider a more simple numerical method
function solve_first_order_equation( a, b ) result( x )
double precision, intent(in) :: a, b
double precision :: x
[...]

Look at what it looks like in your browser:

example2.png
An advanced function documentation

Now, that's some clear and clever documentation, isn't it?

Integrating LaTeX in your documentation

Nothing is more easy as to integrate pretty equations of your unbeatable numerical scheme with your unbelievable skills in LaTeX! Simply copy/paste your LaTeX code between two commands @ f $ (remove the spaces)... and voila!

Example 1

Let's take a short example:

!! recall the euler formula: @f$ e^{i x} = \mathrm{cos} x + i \mathrm{sin} x @f$

which will look like:

Result

Recall the Euler formula: \( e^{i x} = \mathrm{cos} x + i \mathrm{sin} x \)

Example 2

For longer equations, you can of course use multiple lines formulae between the commands @ f [ and @ f ] (remove the spaces):

!! The level set function @f$ \phi_i @f$ is defined as:
!! @f[
!! \begin{cases}
!! \phi_{i}(\boldsymbol{x})<0 & \text{for }x\in\Omega_{i}\\
!! \phi_{i}(\boldsymbol{x})>0 & \text{for }x\notin\Omega_{i}\\
!! \phi_{i}(\boldsymbol{x})=0 & \text{for }x\in\partial\Omega_{i}
!! \end{cases}
!! @f]

Result

The level set function \( \phi_i \) is defined as:

\[ \begin{cases} \phi_{i}(\boldsymbol{x})<0 & \text{for }x\in\Omega_{i}\\ \phi_{i}(\boldsymbol{x})>0 & \text{for }x\notin\Omega_{i}\\ \phi_{i}(\boldsymbol{x})=0 & \text{for }x\in\partial\Omega_{i} \end{cases} \]

Making your text a bit more pretty

Here are the most useful commands to make your text more pretty!

  • *italic* will make the text look italic
  • **bold** will make the text look bold
  • __bold__ will make the text look underlined

You may ask: how did you do those cute bullets below? Simply use - signs, or numbers, in the beginning of the lines, such as:

Example 3

!! Things that I should not do:
!! - divide by 0
!! - slam your finder in the desk's door
!!
!! Things that I should focus on:
!! 1. writting a correct and efficient code
!! 2. document adequately that code above

Result

Things that I should not do:

  • divide by 0
  • slam your finder in the desk's door

Things that I should focus on:

  1. writting a correct and efficient code
  2. document adequately the above code

Making highlighted boxes

You might have noticed all the colored boxes in this page. You can of course do the same with the following predefined commands:

  • @ warning: when you want to warn the reader about a particular point
  • @ todo: when you know that you will have to do something later. This command also add your paragraph to the to do list of the project!
  • @ attention: something that requires attention
  • @ important: an important point
  • @ remember: something to remember
  • @ ex: a given example (do not use @ example which is for a different use)
  • @ par Title content of the paragraph: to add your own boxed paragraph with a custom title
Remember
Do remove the white space after the @ sign for the commands above!

Advanced usage

Sectionning your documentation

Do you want to make a proper and long presentation of a module encompassing several concepts and mathematical discussions?

As in LaTeX, it is pretty easy to add sections to your documentation, similarly as in this page! Simply use the commands # (in the long form: @ section), ## (in the long form: @ subsection) and even ###, depending on the depth you want to give to your section. The advantage of using the @ section is that you can easily make a reference to it, like, for example, a link to Key concepts. See this section for fine ways to do it!

Note
References' name must be chosen carefully as not to interact with other references in the Notus documentation; like in LaTeX. Choose them wisely as not to duplicate a reference! In that case: you will see a warning when building the documentation.

 Example 4

# Sectionning your documentation
## When should I section my documentation?
whenever you want to structure your documentation. check @ref clever_unique_reference_name to do it efficiently.
@subsection clever_unique_reference_name how can i do it?
simply use the associated `#` and `##` keywords!

Adding internal and external references

Now that you have built a detailed documentation with various sections, you might want to add links to internal (within Notus documentation) or external links (towards articles or websites). Trust me, it's very easy!

Two ways to add links

  1. The lazy and quick way: simply type @ref the_reference_name and voila!
  2. The subtle and not-so-long way: type [the text that will be displayed](@ref the_reference_name)
Example

Internal links to Fortran elements

You might someday want to make links between various parts of the code: other modules and functions. Indeed, that is a great idea! Doxygen automatically generate a page for each documented part of the code and, of course, for each routine and type.

Question
How can you do that?

Let's have a look at a more complex example, following the former one:

!> @brief Solve the matrix/vector equation @f$ A x = b @f$
!! @details
!! This function solves the equation @f$ A x = b @f$ where @f$A@f$ is a matrix (of Fortran type: @ref type_matrix)
!! and @f$x, b@f$ are vectors (of Fortran type: @ref type_vector).
!! To do so, we first compute the inverse of the matrix with the function [Matrix inverse](@ref compute_matrix_inverse)
!! @param[in] A: the known matrix @f$A@f$
!! @param[in] b: the known RHS vector @f$b@f$
!! @param[inout] x: the vector solution of the equation
function solve_equation( A, b ) result( x )
type(t_matrix), intent(in) :: a
double precision, dimension(:), intent(in) :: b
double precision, dimension(:) :: x
[...]

Which will look like:

example-references.png
Links and references in documentation

External links and references to articles

Finally, let's say that you have clever external references that justify your numerical method or show experimental results. You might want to share this knowledge with your audience. Here is how you should do it:

  1. Create a References section at the end of your documentation
  2. For every article that you want to appear:
    1. Detailed reference name: add a line starting by a BibTeX style name, like [[1]] or [[AUTHOR00]] followed by the articles authors, name, etc.
    2. Hidden external link: add a line (it will never be displayed!) starting with the chosen name, like [1]: or [AUTHOR00]: followed by the external link to the article (on Science Direct, Springer, etc.)
  3. Make references to them in your documentation like any other reference: by writting [[1]] or [[AUTHOR00]]

... or you can simply copy/paste the example below and adapt it to your needs!

!!
!! All work on [[JANOSI04]] article and now play makes the PhD student a dull boy,
!! according to [[LEVECQUE2017868]]. More references in @ref doc_howtos_doxygen_references.
!!
!! @section my_module_references References
!!
!! - [[JANOSI04]] I. M. Jánosi, D. Jan, K. Gábor Szabó, T. Tél (2004). Turbulent drag reductio...
!! - [[LEVECQUE2017868]] Levecque, Katia & Anseel, Frederik & Beuckelaer, Alain & Van der Heyden, Johan & Gisle, ...
!!
!! [JANOSI04]: https://link.springer.com/article/10.1007/s00348-004-0804-4
!! [LEVECQUE2017868]: https://www.sciencedirect.com/science/article/abs/pii/S0048733317300422
!!

Will look like:

Example
All work on [JANOSI04] article and now play makes the PhD student a dull boy, according to [LEVECQUE2017868]. More references in References to go further.
Note
The command [AUTHOR00]: (with a : after the closing bracket) described in step (2.b) declares a reference link (to the URL written afterwards) labeled AUTHOR00. This label can there be used anywhere in the text: this is what we do in steps (2.a) and (3). We have simply added supplementary [] around the label in order to make it look LaTeX style!

References to go further

Note
The following references are for example purposes only!
  • [JANOSI04] I. M. Jánosi, D. Jan, K. Gábor Szabó, T. Tél (2004). Turbulent drag reduction in dam-break flows. Experiments in Fluids, 37, 219-229
  • [LEVECQUE2017868] Levecque, Katia & Anseel, Frederik & Beuckelaer, Alain & Van der Heyden, Johan & Gisle, Lydia. (2017). Work organization and mental health problems in PhD students. Research Policy