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

          Issue Links

            Activity

            Hide
            jbosch Jim Bosch added a comment -

            Given that the discussion Jonathan linked to suggests LSST's Doxygen setup is fairly brittle, do we dare make such configuration changes?

            I wouldn't let that stand in the way; we can let the RFC be about what we want and what should be obtainable, and if the implementation ticket takes longer because something doesn't work properly, we can treat that as a separate problem.

            Show
            jbosch Jim Bosch added a comment - Given that the discussion Jonathan linked to suggests LSST's Doxygen setup is fairly brittle, do we dare make such configuration changes? I wouldn't let that stand in the way; we can let the RFC be about what we want and what should be obtainable, and if the implementation ticket takes longer because something doesn't work properly, we can treat that as a separate problem.
            Hide
            krzys Krzysztof Findeisen added a comment -

            We seem to have consensus on most things. I'd be happy to resolve the question of alternate keywords by fiat, so the only outstanding issue is the file-level comment block.

            I agree with Jim Bosch that file-level comments rarely have useful content, but removing file pages from the documentation means removing any API element that's not a class member. Could we change the rules so that the file comment is required if and only if the class has functions (including auxiliary functions or operators related to a class), and should not be present if the file only declares classes? Or would that make things too confusing and/or inconsistent?

            Show
            krzys Krzysztof Findeisen added a comment - We seem to have consensus on most things. I'd be happy to resolve the question of alternate keywords by fiat, so the only outstanding issue is the file-level comment block. I agree with Jim Bosch that file-level comments rarely have useful content, but removing file pages from the documentation means removing any API element that's not a class member. Could we change the rules so that the file comment is required if and only if the class has functions (including auxiliary functions or operators related to a class), and should not be present if the file only declares classes? Or would that make things too confusing and/or inconsistent?
            Hide
            jbosch Jim Bosch added a comment -

            Could we change the rules so that the file comment is required if and only if the class has functions (including auxiliary functions or operators related to a class), and should not be present if the file only declares classes? Or would that make things too confusing and/or inconsistent?

            I think this would be okay, though I agree it could make it too easy to forget at times. It sounds like we either have to do that or add a file comment with no content to every file.

            Show
            jbosch Jim Bosch added a comment - Could we change the rules so that the file comment is required if and only if the class has functions (including auxiliary functions or operators related to a class), and should not be present if the file only declares classes? Or would that make things too confusing and/or inconsistent? I think this would be okay, though I agree it could make it too easy to forget at times. It sounds like we either have to do that or add a file comment with no content to every file.
            Hide
            krzys Krzysztof Findeisen added a comment -

            Aha, I did some testing and it appears function documentation is still generated, at least in afw. I don't know if this is because namespace documentation (where the generated documentation appears) is configured differently or because header files get verbatim included anyway.

            I withdraw my objections to removing @file (though the question may need to be revisited if source inclusion is disabled later on).

            Show
            krzys Krzysztof Findeisen added a comment - Aha, I did some testing and it appears function documentation is still generated, at least in afw . I don't know if this is because namespace documentation (where the generated documentation appears) is configured differently or because header files get verbatim included anyway. I withdraw my objections to removing @file (though the question may need to be revisited if source inclusion is disabled later on).
            Hide
            krzys Krzysztof Findeisen added a comment -

            Adopting with changes proposed by Jim Bosch and Jonathan Sick.

            Show
            krzys Krzysztof Findeisen added a comment - Adopting with changes proposed by Jim Bosch and Jonathan Sick.

              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