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`

.

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!

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?

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:

*pretty neat*, isn't it?

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

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:

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

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*!

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:

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

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]

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} \]

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:

!! 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

Things that I should not do:

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

Things that I should focus on:

- writting a correct and efficient code
- document adequately the above code

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!

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.

# 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!

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!

- The lazy and quick way: simply type
`@ref the_reference_name`

and*voila*! - The subtle and not-so-long way: type
`[the text that will be displayed](@ref the_reference_name)`

- Example
`@ref doc_howtos_doxygen_advanced`

will give: Advanced usage`[Geek documenting](@ref doc_howtos_doxygen_advanced)`

will give: Geek documenting

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:

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:

- Create a
**References**section at the end of your documentation - For every article that you want to appear:
- Detailed reference name: add a line starting by a
*BibTeX*style name, like`[[1]]`

or`[[AUTHOR00]]`

followed by the articles authors, name, etc. - 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.)

- Detailed reference name: add a line starting by a
- 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**) described in step (2.b) declares a`:`

after the closing bracket**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*!

- More commands and many tricks are available in the Markdown language documentation
- Doxygen manual page

- 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