On Tue, 31 Jul 2001, Andreas Mohr wrote:
On Tue, Jul 31, 2001 at 04:33:06PM +0000, Bill Medland wrote:
Getting back to what we are and are not allowed to do..
Suppose I am looking at a low-level function that I believe is only 75%-complete (the most important 75% of course and no disrespect meant to those who have got it that far).
One of the problems with it is it is not totally clear EXACTLY what the function should do in some of its more esoteric modes.
To me the first task is to define what it should do and that should be part of the documentation of the function.
IMNSHO full documentation should *not* be included in the Wine tree. Instead, we should rely on MSDN documented stuff wherever possible and only explain quirks/undocumented behaviour/whatever isn't documented.
Having full docu inside the source tree simply bloats it too much IMHO.
Well, let me offer a different opinion.
Wine is an open-source reimplementation of the Win32 API. You can use it to run existing Windows applications and to recompile or develop Win32 applications using Winelib. Now, for me an open-source project that implements an API for which there is no open-source documentation is not complete. Especially for Winelib where the API is part of what we provide to the user, i.e. to programmers using Winelib.
And currently the only documentation of the Win32 API is available from Microsoft as part of the MSDN. I see many problems with that: * it's not open-source (of course). This means we cannot distribute it with Winelib, we cannot generate man pages from it, you cannot generate a winelib-doc package that would contain the man pages of all the Winelib API. * MSDN documentation comes... and goes. Find me the documentation of 16bit functions. The current MSDN versions have eradicated the documentation of all 16 bit APIs. There are tons of aspects of the Win16 environment for which we no longer have any documentation. Then when someone comes to modify some piece of code which is shared between Win16 and Win32 you have no idea if the fix you made for Win32 is not going to break Win16. If Wine had had good independent documentation of the API from the start developpers could refer to this documentation to know whether a change is going to break Win16 or not. * MSDN documentation is often incomplete / slightly incorrect (though people working on Wine should maybe look at it a bit more). So what you propose is that this be *the* documentation for the Win32 API. I think Wine developpers and Winelib users deserve better. And no one using Winelib as a development platform would want to have to go to two places to find documentation. * The MSDN documentation is currently freely available on the Web. Tomorrow it could very well not be the case anymore. Or Microsoft could come up with some sort of click-through license agreement that would make it unsuitable for us. Then Wine and Winelib will be left without any usable documentation.
So I think the functions implemented in Wine should be fully documented. And the only place to do that is in the code source because this is the only place where they have a remote chance of staying up to date (and also where it's most practical to have it).
Of course developpers are very well-known for hating to document stuff so it's going to be pretty hard to get proper documentation. But we should encourage all Wine developpers to write good documentation for the functions they implement/fix, not dissuade them to do so.
Also I agree with you that the strict minimum is to at least document all the undocumented/weird behaviors. Especially since without some sort of documentation the next developper may be tempted to remove what looks like unnecessarily convoluted/obviously wrong code.
Then come the open questions: * How do we get people motivated to write documentation?
Maybe people writing tests (as in using programs/winetest) should/could write documentation. After all to write proper tests you have to understand the API well enough to know what are the corner cases. So you might as well document the functions you test while you're at it. Then people doing the first non-stub implementation of an API would be in a good position to document it. After all if you implement an API aren't you supposed to know how it works? I certainly don't think we should bar code (implementation or tests) that comes with no documentation from getting into CVS. But maybe we could gently ask as a reminder if the submitter could write some doc too.
* Is the current format the most appropriate one?
Well, it's just that I'm a fan of JavaDoc-like formats and that I've always been a bit skeptical of the current system (c2man). Does it still work btw? Is http://www.winehq.com/WineAPI/ up to date? Also it seems we should have documentation on what messages do, especially for things like LVM_XXX. Maybe these could be documented with ListView_XXX macros so that searching for either will return the right page. Similarly there should be a policy wrt. documenting xxxA and/or xxxW. It seems like they should end up being documented on the same (man) page and that obviously we don't want to duplicate the documentation in the source. But there does not seem to be anything in place currently. It would probably be a good idea to also have a general way to group related functions together (e.g. all the MSVCRT execXXX variants).
Did I say yet that I think a testing framework with many tests would be a great boon for Wine? No! Well, I'm going to stop there anyway. Lucky you :-)
-- Francois Gouget fgouget@free.fr http://fgouget.free.fr/ Stolen from an Internet user: "f u cn rd ths, u cn gt a gd jb n cmptr prgrmmng !"