Documenting functions

[Bill Medland]

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.

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.

1. Should the function be completely defined in its header in the source
code (which will probably make the header twice as large as the function)
or should the details be put somewhere else.
2. Are we walking into copyright danger if the Wine documentation of the
function is clearly based on the MSDN documentation, even if we acknowledge
that.
3. Are we interested in that level of documentation?

Bill