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.
