Documenting functions

[Andreas Mohr]

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.

Not to mention that none, zero, zilch of the planned undertakings
in that direction have actually taken off so far.
Docu in general is fine, but duplicated function docu in source tree ?
Avoid as much as possible, I think.

> The particular function currently does not have any true documentation
> within the code; the best documentation of what it does is the code itself,
> and the best documentation of what it should do is the MSDN description of
> the function.
If there's no additional "Wine" information about this function,
then this is perfectly reasonable IMHO (see above).

I'd like to see at most:
function header with comment above with short description of i/o,
additional statements about undocumented/special behaviour.

-- 
Andreas Mohr                        Stauferstr. 6, D-71272 Renningen, Germany
Tel. +49 7159 800604                http://home.nexgo.de/andi.mohr/