[ODE] ODE Documentation

[Remi Ricard]

Hi,
> Documentation is doomed to fail, if there are obstacles for updating.
>   
I agree 100% with that!!!
> Separate documentation into:
> - User manual (tutorial style approach)
> - Reference manual (api)
>   
Again I agree 100% with that !!
> Let user manual be under the community's control: everyone can contribute,
> the obstacle is very small. (-> WIKI)
>   
I really like the php manual approach there is always some interesting 
comments added by the users.

> 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.
> I believe the doxygen tool can do this?
>   
Yes it can.

> 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. 
Usually if you do a change in the code you already have downloaded the code.
Yes someone want to change only the API documentation then yes it need to
download all the source files.

> Some other considerations are that the code gets drowned in comments,
> and it becomes more difficult to internationalize the docs.
For me it make the code easier to readd since you see where the function starts and ends.
Start after a 
/**
*/
With emacs the highlight make the comments stand out. ;-)

I also like the have the api documentation in the code since I don't have to switch
back and forth between the c file and the documentation.
If I want to know what a function do I just have to go up a little and there it is.
I don't have to open the documentation then search the function I need.

N.B. From Doxygen you can produces HTML, pdf, latex et maybe more format.

Remi