"Bill Medland" <medbi01(a)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(a)winehq.com