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

Add detailed C++ documentation guidelines

    XMLWordPrintable

    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

          is triggered by

          RFC - An issue whose primary purpose is to advertise an intent and allow stakeholders to comment. RFC-225 Bring C++ doc standards in line with Python docs

          • Implemented
          relates to

          Improvement - An improvement or enhancement to an existing feature or task. DM-9049 Enable autolinking in Doxygen

          • Done

            Activity

            Ascending order - Click to sort in descending order
            9 older comments
            Hide
            Permalink
            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
            Permalink
            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
            Permalink
            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
            Permalink
            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
            Permalink
            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:

                  Jenkins

                  No builds found.