[ODE] ODE Documentation

[Jon Watte (ODE)]

J. Perkins wrote:

> Some other considerations are that the code gets drowned in comments,
> and it becomes more difficult to internationalize the docs.

Having been an international developer for >20 years, not being a native 
English speaker, it's been my experience that programmers and 
researchers know how to read English. The programmers that need 
translated documentation typically are also new to programming -- i e, 
they typically would have a hard time modeling in ODE.

I'm not saying that translations are an utter waste of resources, but I 
honestly don't think that translation should be front and center when 
designing documentation for ODE. Keeping the English documentation 
actually accurate is more important that making it simpler to translate 
inaccurate documentation.

Further, it's been my experience that keeping documentation in the 
header, and extracting it using Doxygen, is the best way of keeping 
documentation up to date. A separate Wiki or documentation file is less 
likely to be up to date. Keeping documentation in source and headers 
means that they will diverge. Keeping it only in the headers means that 
there's one spot for it, AND you can actually read it while in your 
editor, where necessary.

However, for ODE, there's also a "how to" section that's important (in 
addition to the "reference" section, which Doxygen is good for). 
Luckily, that "how to" section tends to update much more seldom, and can 
probably be put in separate files, included in doxygen using \page or 
something similar.

The doxygen-specific mark-up (@param or \param) is really not that hard. 
You need to know only three things: @param, @return and @note; plus you 
need to know how to format the comments. Doxygen can auto-extract the 
brief comment, and pretty much anything else you want.

/// Apply magic to chosen parts of the world.
/// Parts of the world with magic in them allow the user to fly.
/// @param center A vector3 of the center of magic, where the magic
///    will be strongest.
/// @param radius How far out the magic extends. Objects with center
///    beyond this radius from the center are not affected.
/// @param strength How strong the magic is. Objects heavier than this
///    mass value cannot fly, even while in the magic zone.
void dWorldApplyMagic( dReal const * center, dReal radius, dReal strength );


So, consider this my vote.

Cheers,

			/ h+