Jonathan Sick has written detailed guidelines that standardize Python docstrings and require that developers give a reasonably complete specification of each class, method, or function. The corresponding C++ guidelines are much looser, requiring little more than a descriptive paragraph with few content requirements.

I propose that the C++ documentation guidelines be revised to be more analogous to the current Python guidelines. In particular, I propose:

• that the C++ docs include some comment formatting guidelines, analogous to https://developer.lsst.io/docs/py_docs.html#basic-format-of-docstrings. These can be taken from the rules at https://confluence.lsstcorp.org/display/LDMDG/Documentation+Standards
• that class documentation include the following content, in the following order:
  • a one-line description of the class
  • @deprecated tag (if applicable)
  • one or more summary paragraphs (recommended)
  • @tparam tags (if applicable)
  • @see tags (optional; we should standardize on one of @see and @sa)
  • @note tags (optional; we should standardize on one of @note, @remark, and @remarks)
  • @cite tags (optional)
  • @example tags (optional)
• that public or protected method or function documentation include the following content, in the following order:
  • a one-line description
  • @deprecated tag (if applicable)
  • one or more summary paragraphs (recommended)
  • @tparam tags (if applicable)
  • @param tags (if applicable)
  • @return tag (if applicable)
  • @throws tags (if applicable; we should disallow @exception or @throw for consistency with Python's raises)
  • exception safety (preferably via a custom tag to be added to LSST's Doxygen files)
  • @relatesalso tag (for non-member helper functions; we should standardize on one of @relatesalso and @relatedalso)
  • @see tags (optional)
  • @note tags (optional)
  • @cite tags (optional)
  • @example tags (optional)
• that the use of the @overload tag be documented separately from the basic function documentation, as at present
• that public or protected constant or other variable-like documentation include the following content, in the following order:
  • a one-line description
  • @deprecated tag (if applicable)
  • one or more summary paragraphs (optional)
  • @hideinitializer or @showinitializer tag (optional)
  • @note tags (optional)
  • @cite tags (optional)
  • @example tags (optional)

I have no specific changes to suggest for "File Description Comment for Header Files" or "Package Documentation / Definition", but such changes should be considered within scope of this RFC.

Would it be useful to use an optional @since tag to indicate when a new component was added to its package? I haven't seen much about versioning in the developer documentation, so I have no idea how reasonable this would be.