[ODE] Progress on doxygen?

[Bram Stolk]

Hello,

It is pretty clear to me:

Reference guide (API) should be under developer
control, close to src code... so doxygen.

Programming guide (howto's tutorials concepts)
should be under community control ... so wiki

Once the API is fully documented with doxygen, we
should remove it from the programming guide to
avoid going out of sync.

Also, I've been thinking about the source code
comments. Jason likes them in .cpp, but I think
.h is better: there are a lot of funcs/structs/constants
that are defined in .h only, and not present in .cpp
A simple example is inlined funcs... they dont show
up in cpp files (other than being called).

NOTE: I've made a start with drawstuff.h, as that
one is small and contained. Next step is to do
the core api as well.

I propose that someone who wants to document
a specific part of the api: feel free, commit to
svn, and check the results on 
http://opende.sf.net/docs/
Announce that you are doing/have-done documenting,
so that there is no double effort on the same file.

   Bram

PS: I just saw that the cronjob that needs to update
the doxygen output is still not working, so you need
to do a manual update if you want to see the results
on opende.sf.net probably by logging into the sf
shell servers.


-----Original Message-----
From: Jean de Largentaye [mailto:jlargentaye at gmail.com]
Sent: Fri 4/28/2006 09:45
To: Jason Perkins
Cc: Bram Stolk
Subject: Re: Progress on doxygen?
 
OK, we've had a short discussion with Jason because things were
unclear to me, here's a summary:

- I think it's important to have a good API reference with doxygen so
that people could consult it offline (hey, it's spring, I want to be
outside, even if with a laptop ;)

- I thought we should move API-reference-like information from the
Manual into Doxygen. The Joints page in the wiki-manual is a good
example of what I wanted to move: it's just a beautified API
reference.

- I obviously thought that the stuff would be *moved*, because it
wouldn't be useful to have the same information in two places
(Wiki-Manual and Doxygen), and have them get out of sync.

- Jason was uncomfortable with this. He thinks it's better to keep
things in the Wiki, because they'll get more care. I have to agree.

So the solution would be to actually have the information in both
places, and work on keeping them in sync. I don't mind taking care of
that.

In the meantime, I'm copy-pasting stuff from the wiki into objects.h

Slap me down if you think I'm being too enthusiastic here. :) I know
me, I run out of steam quickly :/

John

On 4/27/06, Jason Perkins <starkos at gmail.com> wrote:
> On 4/27/06, Jean de Largentaye <jlargentaye at gmail.com> wrote:
> > I'm keen on improving the link between the Manual and Doxygen
> > reference, and it seems to me a large part of the manual is exactly
> > what the doxygen docs intend to be.
>
> I'm inclined to remove the "manual" part from doxygen and put it all
> on the wiki. Doxygen would then only be used as an API reference. I
> know that I put a big chunk of the manual into Doxygen, but that was
> before you set the new wiki.
>
> I'm hoping to have some time in May to cut-and-paste a bunch of the
> API information into Doxygen and get 0.6 out the door.
>
> Jason
>