(Resent) Documentation - Reference to MSDN?
jjmckenzie51 at earthlink.net
Wed Jun 30 14:36:23 CDT 2010
Alexandre Julliard <julliard at winehq.org> wrote:
>Erich Hoover <ehoover at mines.edu> writes:
>> Alright, well then I won't do it. Is the existing documentation going
>> to be stripped at some point? It seems to me like we would benefit
>> from more-detailed function descriptions in the auto-generated API
>> documentation. I think it would save a lot of time for new developers
>> to get their feet wet if they were able to see directly in the source
>> what the different functions are supposed to do (as best as we know)
>> and exactly what applications will trigger known edge cases (or if
>> there's a test for a given situation).
>That's what the source code and test cases are for. If you rely on the
>function documentation you are in trouble anyway, nobody bothers to
>update it when new behaviors are discovered.
>If you really want to write good API documentation, as opposed to the
>current useless one-sentence-per-parameter description, you'd need
>probably a text 10 times the size of the source code for each
>function. That can't go in the source files.
How about some place on the Wiki along with an implementation status. That way we can also annotate items that are missing in MSDN (I just re-stumbled across something in my latest Richedit tests) as well. This would help greatly in our progress towards current and future implementations of the Windows API.
And I agree, adding all of this to the source would make it unwieldy.
More information about the wine-devel