How to write doc for C++ functions

I’m a huge fan of the Javadoc style guide, which uses
almost the same markup as doxygen.

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

Thanks for this, I’ve got an open PR adding a lot of doc and will sharpen it up a bit before bugging you about reviewing it.

Reviewing it’s what caused me to do this, then I remembered I
wrote this on the stan-dev/stan wiki:

  • Bob