When we wrote our documentation generator in documentation.h, there was not a set standard for documenting functions in sphinx. Since release 1.3 (which is now required by most of our software), there is:

http://www.sphinx-doc.org/en/stable/ext/napoleon.html

The napoleon extension is already loaded by most of our software, so it makes sense that the generator follows one of the docstring standards defined on that manual page. Some of our python-based docstrings already follow the "Google" style:

http://www.sphinx-doc.org/en/stable/ext/example_google.html#example-google

It would be good to get the C++ docs matching that.