On 02/27/2011 05:55 PM, Alexandre Julliard wrote:
The other reason is that a decent documentation of the Windows API would be huge; look at how much information there is on MSDN, and that's still incomplete. It's completely impossible to maintain something of that size in the middle of the source code. As long as it's inside the source, it will just be one or two sentences per function, and maybe a list of parameters. That's not useful documentation.
Hmm. Reviewing c2man.pl: The reason there are only one line comments on the parameters is because that is all the extraction program allows. I had access to commercial grade source code for some years (_NOT_ Microsoft!) and the library function documentation was indeed in the source files and there was a program that extracted the documentation and that was published and sold. So, I have to disagree that the situation is impossible. Yes, it is _hard_ to do, and duplicating MSDN should not be the goal. If done right the embedded documentation should add value to the code. Such things as what has and has not been implemented and _why_ might be helpful. It might even be useful to describe _how_ some of the stuff is done. Oh, and the total amount is indeed huge, but each piece is not. It's just that there are _lots_ of pieces. The way to eat an elephant is one bite at a time... Max
