Please help me with document extraction.

[Alexandre Julliard]

Max TenEyck Woodbury <max at mtew.isa-geek.net> writes:

> I'd also like clarification on why you think it does _not_ belong in
> the source code. Some projects insist that documentation _has_ to be
> part of the source code so that it will be properly maintained.

That's because in most projects the API is defined by the
implementation, and when you change the code you want to update the
documentation accordingly. The Windows API is defined by Microsoft and
is independent of the Wine source. If you want to store it along with
the code you'd have to put it inside the Windows source.

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.

The reality is that this is not going to happen; nobody is going to
invest the time to write real documentation for even a subset of the
API. There's just no point, and MSDN is good enough for most needs. And
I'm not interested in developing infrastructure for something that won't
happen. If you want to prove me wrong, start writing it. Once you have
properly documented 100 functions, we can discuss what extra
infrastructure is needed for the remaining 50,000.

-- 
Alexandre Julliard
julliard at winehq.org