Max TenEyck Woodbury max@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.