[ODE] Automatic code documentation tool

[Russ Smith]

Fredrik Sandström wrote:
> Hi, was wondering if you are using any sort of autodoc tool for the
> ode internals code or are planning to do that? Using one like doxygen
> forces a standard on how and what to document in function headers etc
> and the possibility to browse the code online can also be helpful.

i have not planned anything yet for the internals, only the external
API. for the external API i dont use doxygen etc because it creates
"repository noise" - what i mean is that the API docs are often written
and re-written separately from the code, by various different people -
doxygen and the like ask that they be checked into the same source
file, which can cause annofing checkin conflicts and also make it
harder to identify the code changes that are made to a source file in
the event a backout is needed.

the current ODE API documentation system has all the docs in a separate
file (ode.doc) that can is automatically scanned to make sure it is in
sync with the ODE headers.

as far as the internals go, i've commented where i feel it's
necessary (heavily in same cases), but not in any consistent manner.
for now, if people need stuff explained i'll add to the function
comments on a case-by-case basis.

russ.

--
Russell Smith
http://www.q12.org