design comments in code or in tests?

Hi,

here's another one you WineConf folks may want to discuss.

I've already expressed that there are not enough comments
in mmdevapi's code.  I thought about adding some, but wondered
whether there's any value in using the header format that
old code in Wine uses/used for automated doc. Generation
(whatever the exact format was).

For instance, comments ought to document GetPosition's
contract in sufficient detail:
 - 0 <= GetPosition <= sum of written samples (modulo Frequency)
 - underruns don't count, it's no wall clock
 - monotically increasing(?)
 - should reflect speaker position, not buffering (MSDN says that)
Don't look up MSDN.  If that were complete enough, I would not
have had the need to write as many tests as I did.

Then I thought about placing comments in dlls/*/tests/ instead,
because the test code is thrown away less often than the dll code.
Seriously.

Regards,
    Jörg Höhle