Following discussion on RFC-225 and its implementation tickets, the Documenting C++ Code section of the DM Style Guide has been reworked with more detailed guidelines that strike a compromise between the numpydoc-like convention we follow in Python, the capabilities of Doxygen, and differences between C++ and Python.
Major changes include:
- Documentation comment style is standardized on
/**or///delimiters and tags like@param./*!and\paramare discouraged in new code. - Like in the Python docs, detailed descriptions of method parameters, return values, etc. are encouraged. Documentation is structured using Doxygen’s built-in commands rather than headers.
- File-level comments, in particular the
@fileand@authortags, are no longer required or encouraged.
We haven’t made any breaking changes to the configuration of Doxygen itself, so previously written comments will build as before.