Building documentation from functions source code
From OpenFLUID
The writing of the documentation of a simulation function is an important part of the development process.
In order to help function designers and developers, the func2doc tool can interpret the source code of the .cpp file to generate documentation. This documentation is built using the function signature and free text located as comments in the text.
The func2doc tool generates a LaTeX file that can be transformed on-the-fly as a PDF file or HTML content. The free text part can contain LaTeX commands, especially for maths formulas. Using the default template, the generated document will be structured as follows:
- title with author(s)
- brief description
- handled data (variables, properties, function parameters, events, extrafiles, ...)
- the free text
The free text part must be placed into comments, between the <func2doc> and </func2doc> tags.
/*
<func2doc>
This is the free text part of my function. I can write \latex commands and formulas like $f(x)=1/x$
</func2doc>
*/
To know how to use the func2doc tool, just type the following command in your terminal :
openfluid-engine --buddyhelp func2doc
The standard usage to build documentation from a .cpp file and build the PDF on-the-fly is :
openfluid-engine --buddy func2doc --buddyopts inputfile=MyFunction.cpp,outputdir=/path/to/output/directory,pdf=1
