Please help me with document extraction.

[Max TenEyck Woodbury]

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