|
version 0.6.0
|
|
|
version 0.6.0
|
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.
@ 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
(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!
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...
!> 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!
To shown you how it works, look at this simple example:
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):
Adding a few more knowledge to the function, we can write this new documentation:
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:
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 \( \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 underlinedYou 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:
Things that I should focus on:
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 titleDo 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!
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!
@ref the_reference_name and voila@ref doc_howtos_doxygen_advanced will give: Advanced usage[Geek documenting](@ref doc_howtos_doxygen_advanced) will give: Geek documentingYou 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.
Let's have a look at a more complex example, following the former one:
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:
[[1]] or [[AUTHOR00]] followed by the articles authors, name, etc.[1]: or [AUTHOR00]: followed by the external link to the article (on Science Direct, Springer, etc.)[[1]] or [[AUTHOR00]]... or you can simply copy/paste the example below and adapt it to your needs!
Will look like:
[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!
1.9.5