Documenting functions

[Jeremy White]

[Resend due to exim crash; thanks Ove]

 >> I'd much rather have developers spend their time writing code. Making
 >> them duplicate the whole MSDN documentation would be a huge waste of
 >> their time. Our resources are not infinite, and it's much more useful
 >> to have 100% API coverage with no docs at all than 50% coverage and
 >> tons of docs.


     I think this is a dangerous attitude to take.  I think that
you cannot (and should not) attempt to force volunteer developers to add
documentation to code.  However, there are some few of us,
who don't feel that the job is satisfactorily done until
the documentation reflects important things that we've learned.

     I would say that I would rather have 100% of the effort a
particular developer *wants* to put in, rather than only
have his/her coding efforts.

     If I, like Bill, spend 24 hours ripping my hair out to
learn some oddball things, I want a place to put those things.
I want someone else (or an older version of me) to have a
chance to not have to learn those things the hard way.

     Please don't misunderstand me.  I agree that we shouldn't
try to replicate MSDN.  I'm not even sure we should provide
minimal documentation like parameter lists and return values.
Further, I agree that where it makes sense, the best place
for comments is inline with the relevant code.
However, I think that there should be a standard function
header, with a standard place to put notes and comments
in general about a function.

     I have been trained, and I suspect that many of us have
been trained, to look at a function header for general
tips and tricks before diving into the code.  I know
this is sacriledge to you, Alexandre, but there are some
of us who like to quickly look at a function, rather than
always reading the code to understand it completely.

<in joke>
     Finally, I think all the code would be dramatically
improved, in fact, I bet we'd be at Wine 1.0 by now,
if there were nice big horizontal separator lines everywhere.
</in joke>