Doxygen

Every developer is responsible to provide documentation. http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html#fortranblocks

To document function or subroutine

!---------------------------------------------------------------------------
!> @brief <BRIEF_DESCRIPTION>
!> @details <DETAILED_DESCRIPTION>
!> @param[<IN or OUT or INOUT>] <PARAM1> <DESCRIPTION>
!> @param[<IN or OUT or INOUT>] <PARAM2> <DESCRIPTION>
function function_name(<PARAM1>,<PARAM2>)

The good way to document fortran module is to copy and paste this:

!> @ingroup <DIRECTORY_NAME>
!> @author <MODULE_AUTHOR_NAME_AND_AFFILIATION>
!> @brief <BRIEF_DESCRIPTION>
!> @details <DETAILED_DESCRIPTION>
module <MODULE_NAME>
...
end module <MODULE_NAME>

Every directory of the software should have an entry in the “Libraries” tab on the website generated by Doxygen. To create this entry, edit the fortran file “_doc.F90” and add the documentation of all fortran modules available in this directory. Add also some examples.

To see your documentation, remove the line containing your directory in file:

doc/doxygen/Doxyfile (line 691).

Type ‘make doc’ in build directory. To check the results, open:

selalib/doc/build/html/doxygen/html/namespaces.html

Laura Mendoza from IPP Garching wrote the script (https://github.com/lasofivec/python-scripts/blob/master/make_sll_doxygen_doc.py) to comment the fortran modules, function and subroutines of a file. Basically it will write the comment lines that you can find above. It doesn’t write the documentation for you (of course) but it could save some time!