The WineAPI wiki.

Max TenEyck Woodbury max at mtew.isa-geek.net
Mon Aug 2 11:16:15 CDT 2010


On 08/02/2010 11:18 AM, James Mckenzie wrote:
> Max TenEyck Woodbury<max at mtew.isa-geek.net>  wrote:
>
>> On 08/02/2010 07:00 AM, Dmitry Timoshkov wrote:
>>> Max TenEyck Woodbury<max at mtew.isa-geek.net>   wrote:
>>>
>>>> I have started the WineAPI wiki at
>>>>
>>>> https://sourceforge.net/apps/mediawiki/wineapi/index.php?title=Main_Page
>>>
>>> You have chosen not very good name. There is no such a thing as Wine API,
>>> Wine implements Win32 API, and doesn't specify/add anything custom to it.
>>> The name "WineAPI" implies that Wine defines its own API which is not true,
>>> and is confusing.
>>>
> This should be named, the Windows32/Window64 API as implemented by Wine
> Documentation site.  That is what it is.  We have found shortcomings in
> the MSDN documentation (I'm dealing with this right now in one function
> call for Richedit.)  This should be a collaborative site where Wine
> developers, Windows on Wine developers and others can place information
> on what Wine has implemented today, what needs to be implemented (with
> case code and discoveries) and what Wine cannot implement.
>
Hmm, I may change the brief project description to match that. I will
think about it...

>> There is a lot of information specific to Wine, particularly its
>> internal structure, that is not shared with Microsoft's product.
>> Further, there is a little confusing and incorrect information in the
>> Microsoft documentation. Bluntly, the Microsoft documentation is what
>> they want it to be. We need to document what it really is.
>>
>> We have tried to embed API documentation in the source code. That has
>> not worked as well as it could. Alexandre Julliard has said as much. I
>> think that having good documentation will help the project. Not having
>> good documentation can and does hurt Wine in my opinion. I also think
>> that trying to prevent the creation of that documentation might be
>> harmful.
>
> AJ has stated that documenting the Windows API and internal API calls
>should NOT be documented just in the source.  It bloats the source code
>terribly and can make code unreadable.
>
> I agree that this Wiki should only be used to document the external
> interfaces to Wine as we implement Windows32/Windows64 API/ABI calls
> and what we have found in our testing that is different than MSDN.
> We should NOT duplicate MSDN where is is proper, but rather have a
> note that states MSDN and other sources have been found to be proper.
>
I disagree. Really good documentation includes 'Theory of Operation'.
Of course we do not have that for the Microsoft code, but it *may* be
helpful for our own code. I think documenting our test code would also
be useful.

There should be links to the Microsoft documentation in each article,
but Microsoft has been known to move their documentation around without
maintaining redirects. To avoid being at Microsoft's mercy in this, a
summary (*not* a duplicate) of the Microsoft articles, which would be
fair use, should be maintained.

- Max



More information about the wine-devel mailing list