"Bill Medland" medbi01@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