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.