[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>
-
Jeremy White