[ODE] ODE Documentation

[J. Perkins]

On 3/30/06, Bram Stolk <bram at sara.nl> wrote:
> To lower the obstacle for updates to ref manual: keep reference doc and
> source code in same file. This is so called 'literate programming'.
> The ref doc is then generated daily from svn sources by scanning for
> c++ comments in the source that preceed the func defs.

The drawback to this approach is that it requires someone to go
download all of the source code, then figure out the doxygen (or
whatever) syntax, make updates without breaking the build, and then
get everything checked back in. ODE seems to have a large casual
audience that isn't on this list (the activity logs show ~100
downloads a day!) and is integrated into a lot of third-party
projects. I'd hate to scare away potential contributions from these
less-technical (or just less-interested) folks.

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

Not ruling out the doxygen approach, I've used it myself in the past,
just offering a counterpoint.

Jason