Documenting functions

[Francois Gouget]

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 at 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 !"