Uploaded image for project: 'Request For Comments'
  1. Request For Comments
  2. RFC-225

Bring C++ doc standards in line with Python docs

    Details

    • Type: RFC
    • Status: Implemented
    • Resolution: Done
    • Component/s: DM
    • Labels:
      None

      Description

      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.

        Attachments

          Container Issues

            Issue Links

              Activity

                People

                • Assignee:
                  krzys Krzysztof Findeisen
                  Reporter:
                  krzys Krzysztof Findeisen
                  Watchers:
                  Jim Bosch, John Parejko, John Swinbank, Jonathan Sick, Joshua Meyers, Kian-Tat Lim, Krzysztof Findeisen
                • Votes:
                  0 Vote for this issue
                  Watchers:
                  7 Start watching this issue

                  Dates

                  • Created:
                    Updated:
                    Resolved:
                    Planned End:

                    Summary Panel