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
- is triggering
-
DM-7891 Add detailed C++ documentation guidelines
- Done
-
- Done
-
- Done
-
- Done
- relates to
-
- Done
Activity
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?
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? 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.
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).
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). Adopting with changes proposed by Jim Bosch and Jonathan Sick.
Krzysztof Findeisen
added a comment - Adopting with changes proposed by Jim Bosch and Jonathan Sick. 
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.