Documenting functions

[Alexandre Julliard]

"Bill Medland" <medbi01 at accpac.com> writes:

> Ay, there's the rub.  It isn't our function.  It';s Microsoft's function. 
> Now was it Holub or McConnell that complains about functions having weird
> behaviour on certain inputs.

IMO Microsoft functions need less documentation than internal ones,
since there is MSDN and other countless books about Windows. You can
assume that people reading your code already know what the various
APIs are supposed to do.

> The biggest problem, I believe, is the functions that take flags.  Bear in
> mind that a single DWORD argument used for flags is equivalent to up to 32
> boolean arguments.  Documenting the relationship between those is a pain
> but it needs to be done if we expect compatibility.

This is clearly something that is best documented with code, not with
text. You may need pages of text to describe the flags behavior in
English, while with code it's usually only a few lines, plus a few
comments here and there.

This doesn't mean it wouldn't be a good thing to also have the full
description in English; but in a separate document, not in the code.

-- 
Alexandre Julliard
julliard at winehq.com