I'd have to agree with you guys on this one. One thing I can think of that I would like to take on (given enough time to do it all) is create a wiki page that I can use to document all of the fixme's, warn's and err's that occur in the source, and then ask anyone that is contributing code to update it when they add/remove one of those. For example, it might be helpful to a user to know that "err:midi:OSS_MidiInit ioctl on midi info for device 0 failed" is more of a fixme than an error, and exactly what that "gibberish" means, so that they dont go reporting it (making a dupe report), etc..
Dustin
Dimi Paun wrote:
On Wed, 2005-06-15 at 13:25 +0200, Alexandre Julliard wrote:
Yes, but it doesn't really help if the comments are not up to date. I'd prefer to make sure it's dead easy to update the doc directly rather than ask people to maintain comments and then have to come back and sync with the doc. That may mean putting the doc directly in the source, or having a wiki page than everybody can update, I don't know; but I think we should be able to find a better mechanism than these magic comments.
Putting the documentation into the comments may very well be the way to go. But this implies putting a more embellished magic comment in. If you don't want it in the code, at lest we need a pointer/marker. So either way we need an easy to parse/grep comment.
Personally I think that embedding the docs in the documentation is probably the way to go. For code related docs, I think it's the only feasible approach (see how successful Javadoc is).
We can start with a just a marker and a Janitoral task of enhancing the markers with the appropriate markup and documentation. We just need to decide what to do, and document it on the Wiki. I'm sure folks will help out with this if there is a clear direction on where we want to go.