On 08/02/2010 11:18 AM, James Mckenzie wrote:
Max TenEyck Woodbury<m...@mtew.isa-geek.net> wrote:
On 08/02/2010 07:00 AM, Dmitry Timoshkov wrote:
Max TenEyck Woodbury<m...@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
