Uploaded image for project: 'Data Management'
  1. Data Management
  2. DM-7891

Add detailed C++ documentation guidelines

    Details

    • Story Points:
      6
    • Epic Link:
    • Sprint:
      Alert Production F16 - 11, Alert Production F16 - 11b, Alert Production F16 - 11c, Alert Production S17 - 12, Alert Production S17 - 1, Alert Production S17 - 2
    • Team:
      Alert Production

      Description

      Modify the page Documenting C++ Code in the LSST Developer Guide to conform to RFC-225, including changes made in the discussion section. The final result should look similar to Documenting Python APIs.

      The page is considered part of the C++ Style Guide, so these changes must be approved by the System Architect. They should also be approved by as many senior C++ developers as is practical.

        Attachments

          Issue Links

            Activity

            Hide
            rowen Russell Owen added a comment -

            For what it's worth, I agree with Jonathan Sick about cross-references.

            Show
            rowen Russell Owen added a comment - For what it's worth, I agree with Jonathan Sick about cross-references.
            Hide
            krzys Krzysztof Findeisen added a comment - - edited

            I can remove this rule, but it would require a change to the base Doxygen config to enable autolinking (DM-9049).

            Show
            krzys Krzysztof Findeisen added a comment - - edited I can remove this rule, but it would require a change to the base Doxygen config to enable autolinking ( DM-9049 ).
            Hide
            krzys Krzysztof Findeisen added a comment -

            The text has been improved following review comments here and on GitHub.

            Kian-Tat Lim, can you sign off on the document at https://developer.lsst.io/v/DM-7891/docs/cpp_docs.html?

            Show
            krzys Krzysztof Findeisen added a comment - The text has been improved following review comments here and on GitHub. Kian-Tat Lim , can you sign off on the document at https://developer.lsst.io/v/DM-7891/docs/cpp_docs.html?
            Hide
            ktl Kian-Tat Lim added a comment -

            Generally looks great! Some relatively small things to correct or think about.

            For the "add example?" comments, feel free to ignore if you think that the section is so obvious that no example is really needed.

            It would be nice to reuse the common text with the Python doc standard, but I'm guessing that doing so would make the document unwieldy.

            Show
            ktl Kian-Tat Lim added a comment - Generally looks great! Some relatively small things to correct or think about. For the "add example?" comments, feel free to ignore if you think that the section is so obvious that no example is really needed. It would be nice to reuse the common text with the Python doc standard, but I'm guessing that doing so would make the document unwieldy.
            Hide
            krzys Krzysztof Findeisen added a comment -

            Merged with final changes by K-T. Many thanks to everyone for your feedback!

            Show
            krzys Krzysztof Findeisen added a comment - Merged with final changes by K-T. Many thanks to everyone for your feedback!

              People

              • Assignee:
                krzys Krzysztof Findeisen
                Reporter:
                krzys Krzysztof Findeisen
                Reviewers:
                Jim Bosch, Kian-Tat Lim, Russell Owen
                Watchers:
                Jim Bosch, Jonathan Sick, Kian-Tat Lim, Krzysztof Findeisen, Russell Owen
              • Votes:
                0 Vote for this issue
                Watchers:
                5 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved:

                  Summary Panel