Automatic docstring generator should adopt one of "Napoleon" styles
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.