iLab Neuromorphic Robotics Toolkit
0.1
|
Use the following instead of plain strings in your comments:
For example:
Generally speaking, our goal is that users should be able to access information:
See how it's done for GenericImage.
Modules
section of the documentation: And note how we use the arrobas curly braces to here include into our group all the operators that will be defined.
For classes that have helpers, for example, some enums that define parameters of functions associated with the class: Just define your group to only include the class; then indicate for each helper that it relates to the class. This will list the helpers in the doc page of the class, as opposed to cluttering the page of your group. See for example how it's done in Image.H where:
However, for enums that are only used in functions and cannot be related to a class, we mush add those to the group where the function belongs. Have a look at Text.H for an example: TextAnchor is documented and added to textdrawing group, like the drawText() function is.
NRT_MACRO_
NRT_
For enums defined using NRT_DEFINE_ENUM_CLASS, we basically manually instruct doxygen that we are creating a new class. Adapt the following to your own enums:
Try as much as possible to create test-XXX.C
files in the tests/
directory, and to focus each one on fully exercising a particular class or set of functions.
Either make a little test program that does something, like test-Component.C where people can play with parameters, etc, or use the boost testing framework to check a bunch of things, like test-GenericImage.C
The way examples are treated in doxygen is as follows: one declares a file as being en example somewhere, using the \example
directive. That file is then scanned for classes, functions, etc, and for the ones that are found, an Examples:
section is added to their documentation.
In NRT, we also instruct Doxygen that all files in tests/
are examples (see doc/doxygen.cfg
)
Note that sometimes doxygen does not make the connection between a class and an example file. For example, in test-Module.C
we do show how nrt::Module works, but only via classes that derive from nrt::Module ... In such cases, add an explicit link to the example file in the doc of your class. For instance:
There is a bit of trial and error that is required here. After you add a new example file, run a make
doc
, and check out the classes that you think should link to your example. If you don't find the relevant Examples:
sections in there, just add the explicit link. The easiest is to look at your example file as marked up by doxygen and as it appears in the Examples
tab at the top of your doxygen pages: everything that is clickable in there will be correctly linked (which you can check by clicking on those classes, functions, etc and verifying they have an Examples:
section).
It may help doxygen if you fully qualify the classes or functions you use in your examples. For example, in test-Async.C we clearly specify nrt::async() (as opposed to using the namespace nrt and then calling async() without the namespace qualifier). This properly links test-Async.C to the documentation of nrt::async().