(Resent) Documentation - Reference to MSDN?

[Erich Hoover]

On Fri, Jul 2, 2010 at 3:51 AM, Dmitry Timoshkov <dmitry at codeweavers.com> wrote:
> James McKenzie <jjmckenzie51 at earthlink.net> wrote:
>> ...
>> It is NOT our purpose to provide sample code or anything like it.   That
>> is what MSDN is there for.  To assist Microsoft Developers working with
>> Windows products to produce Windows programs.  Not to assist or aid any
>> others in the pursuit of a 'look alike' API that just happens to run on
>> UNIXy operating systems.
>> ...
>
> Who are those "we"? I personally don't need anything listed above.

"We" is whomever wants to help with this idea.  Preferably, many
people like you that are already intimately aware with the details of
at least some of the API.  This kind of resource would be most
beneficial for those that are either just getting started contributing
to Wine or those branching out to fix something outside of their area
of expertise.  I know that I've been spending a large fraction of my
free time researching how Windows handles animated cursors,
consolidating the links to all the resources and the tidbits of
information I've found would likely save anyone else looking into the
same problems a lot of time.  I still don't know what
GetCursorFrameInfo does, and I have a hunch that it might be useful in
doing a proper animated cursor implementation.

> Quoting Alexandre's response:
> "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."

I would argue that good documentation is just as important as source
code and test cases.  It can save a lot of time in introducing new
people to the code, even if it is somewhat out of date.  On projects
I've been in charge of in the past my policy has always been that the
documentation is in the code and generated by a script - that usually
works as a pretty good eyesore to get developers to update it as they
go.  However, since that's off the table there are other methods for
keeping documentation up to date.  For example, a "Documentation
Tracker" could be setup for the documentation folks to review new
commits and see if they warrant an update to the documentation.

Erich Hoover
ehoover at mines.edu