I’m a huge fan of the Javadoc style guide, which uses
almost the same markup as doxygen.
http://www.oracle.com/technetwork/articles/java/index-137868.html
In the ideal world, the doc is precise enough to form
the foundation of testing. That includes all the error conditions
and what gets returned.
One of the key elements is that the first sentence should be a concise
summary of what the function does. This should take the form of
a a complete imperative sentence (present tense, no subject),
as in:
/**
- Return first argument divided by second argument.
…
It should not be a rehash of the function name or operation, as in:
/**
- Division operator.
…
There should be documentation for what each of the arguments
is doing and what legal values are and what exceptions are thrown
for illegal values.
The arguments should all come after, with @tparam, @param, @return, @throws
in that order, with no space necessary. These should be
nouns, so no initial caps or final periods.
- Bob