Guess what? In light of the ODE focus of Odejava (that is maintain a tight binding to the underlying API - not trying to work around limitations etc...) I have added a new tag to the ant javadoc task and created a taglet in java code.
The tag is @ode. Odejava API developers such as Jani and I can use it to inform the users though the javadoc which ODE methods are used and why.
This is important because as I discovered - there are some oddities of ODE that can cause strange bugs. At least this way you can basically work out what ODE methods are being called for debugging.
It also means you can quickly lookup the ODE docs to check what the function does if it isn't clear. So basically it can remove some assumptions and guesswork for the user.
A further step when I add log4j logging to Odejava would be to actually log every single call to ODE, again for debugging (only if turned on however...).
An example can be seen on this method:
http://odejava.org/javadoc/org/odejava/Geom.html#removeFromSpace()cvs log:
1
2
3
4
5
6
7
8
9
10
11
12
13
| added new @ode tag to the javadoc task.
The tag can be used to document which ODE methods are called and why.
For example:
The method Body.delete calls Ode.dBodyDestroy(bodyId); So in it's javadoc comment, you would add the line:
@ode dBodyDestroy destroys the body
The comment that you add describes the USE of the ODE method - NOT the function of that method (as people should look up the docs for this).
Please use this tag :) |
Cheers,
Will.
