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

Transfer relevant C++ doc guidelines from Confluence to Developer Guide

    XMLWordPrintable

    Details

      Description

      Investigation supporting RFC-225 revealed that some rules in the Confluence documentation guidelines (e.g., the use of @ for Doxygen tags, or placing all documentation at the point of declaration) are not present in the developer guide. Ensure all relevant rules are present in the final documentation (senior developers have the final word on which rules are relevant).

        Attachments

          Issue Links

            Activity

            No builds found.
            krzys Krzysztof Findeisen created issue -
            krzys Krzysztof Findeisen made changes -
            Field Original Value New Value
            Epic Link DM-7362 [ 26448 ]
            krzys Krzysztof Findeisen made changes -
            Link This issue has to be done after DM-7891 [ DM-7891 ]
            krzys Krzysztof Findeisen made changes -
            Labels SciencePipelines documentation, SciencePipelines Standards documentation,
            krzys Krzysztof Findeisen made changes -
            Link This issue is triggered by RFC-225 [ RFC-225 ]
            krzys Krzysztof Findeisen made changes -
            Sprint Alert Production F16 - 11 [ 289 ]
            krzys Krzysztof Findeisen made changes -
            Sprint Alert Production F16 - 11 [ 289 ]
            krzys Krzysztof Findeisen made changes -
            Rank Ranked lower
            krzys Krzysztof Findeisen made changes -
            Labels SciencePipelines Standards documentation, SciencePipelines Standards dm-dev-guide documentation,
            krzys Krzysztof Findeisen made changes -
            Component/s Developer Infrastructure [ 10712 ]
            krughoff Simon Krughoff made changes -
            Epic Link DM-7362 [ 26448 ] DM-8472 [ 28104 ]
            krzys Krzysztof Findeisen made changes -
            Sprint Alert Production S17 - 3 [ 605 ]
            krughoff Simon Krughoff made changes -
            Epic Link DM-8472 [ 28104 ] DM-9680 [ 30785 ]
            Hide
            krzys Krzysztof Findeisen added a comment - - edited

            Also change the following mistakes in the current dev guide:

            • The guide recommends using @code to delimit examples. This runs contrary to the rule preferring Markdown formatting, and may cause rendering errors if the documentation block begins each line with a *.
            • The guide should warn against trying to provide multi-paragraph parameter descriptions.
            Show
            krzys Krzysztof Findeisen added a comment - - edited Also change the following mistakes in the current dev guide: The guide recommends using @code to delimit examples. This runs contrary to the rule preferring Markdown formatting, and may cause rendering errors if the documentation block begins each line with a * . The guide should warn against trying to provide multi-paragraph parameter descriptions.
            krzys Krzysztof Findeisen made changes -
            Status To Do [ 10001 ] In Progress [ 3 ]
            Hide
            krzys Krzysztof Findeisen added a comment - - edited

            Rules on confluence page:

            • General
              • Emacs file format line (present in C++ docs, absent in Python)
              • Copyright statement (present in C++ docs, absent in Python)
              • File comment (superseded by RFC-225)
              • Class comment (content already present; recommend not requiring @class or lists of class members)
              • Function comments (already present)
              • @todo rule (superseded by RFC-307)
              • @note rule (already present)
            • C++
              • Document items at declarations (already present)
              • Use @ rather than \ (already present)
              • Use /* */ or /< (superseded by review discussion on DM-7891)
              • Inline parameter documentation must be used consistently (superseded by DM-7891 review discussion)
              • Documented parameters must match real parameters (ported)
              • Examples
                • Brief descriptions ended by either newline or period (ported)
                • Use of @defgroup (superseded by RFC-225)
                • @note (already present)
                • @see can use external links (ported)
                • @throw (superseded by RFC-225)
                • @todo (superseded by RFC-307)
                • @warning (already present)
                • preamble (superseded by RFC-225)
                • class declaration (already present)
                • function declaration (already present)
                • @overload (already present)
                • full file (not ported)
            • Python (superseded by RFC-214)
            Show
            krzys Krzysztof Findeisen added a comment - - edited Rules on confluence page: General Emacs file format line (present in C++ docs, absent in Python) Copyright statement (present in C++ docs, absent in Python) File comment (superseded by RFC-225 ) Class comment (content already present; recommend not requiring @class or lists of class members) Function comments (already present) @todo rule (superseded by RFC-307 ) @note rule (already present) C++ Document items at declarations (already present) Use @ rather than \ (already present) Use /* */ or /< (superseded by review discussion on DM-7891 ) Inline parameter documentation must be used consistently (superseded by DM-7891 review discussion) Documented parameters must match real parameters (ported) Examples Brief descriptions ended by either newline or period (ported) Use of @defgroup (superseded by RFC-225 ) @note (already present) @see can use external links (ported) @throw (superseded by RFC-225 ) @todo (superseded by RFC-307 ) @warning (already present) preamble (superseded by RFC-225 ) class declaration (already present) function declaration (already present) @overload (already present) full file (not ported) Python (superseded by RFC-214 )
            krzys Krzysztof Findeisen made changes -
            Description Investigation supporting RFC-225 revealed that some rules in the Confluence documentation guidelines (e.g., the use of @ for Doxygen tags, or placing all documentation at the point of declaration) are not present in the developer guide. Ensure all relevant rules are present in the final documentation (senior developers have the final word on which rules are relevant). Investigation supporting RFC-225 revealed that some rules in the [Confluence documentation guidelines|https://confluence.lsstcorp.org/display/LDMDG/Documentation+Standards] (e.g., the use of @ for Doxygen tags, or placing all documentation at the point of declaration) are not present in the developer guide. Ensure all relevant rules are present in the final documentation (senior developers have the final word on which rules are relevant).
            Hide
            krzys Krzysztof Findeisen added a comment - - edited

            Jonathan Sick, you might have answered this already, but do you want to add something about the Emacs hint and the correct copyright block to the python documentation? I think that's the only bit on the confluence page that's still relevant to Python.

            John Swinbank, given your recent remark on ordinary TODO: comments, I assume @todo is also something we should no longer be using? (Current list here).

            Show
            krzys Krzysztof Findeisen added a comment - - edited Jonathan Sick , you might have answered this already, but do you want to add something about the Emacs hint and the correct copyright block to the python documentation? I think that's the only bit on the confluence page that's still relevant to Python. John Swinbank , given your recent remark on ordinary TODO: comments, I assume @todo is also something we should no longer be using? (Current list here ).
            Hide
            swinbank John Swinbank added a comment -

            As per my earlier comment, I'm quite strongly against just using some variation on "todo" in the code to mark areas where further work is needed. I have no objection to using this in conjunction with a JIRA ticket, though.

            I'm actually not sure who has final say on this, though. The description of this ticket mentions "senior developers"; it may be that Kian-Tat Lim claims some jurisdiction here; and since "todo" in particular relates to tracking future work, I reckon it's particularly of relevance to T/CAMs. Maybe worth an RFC to ensure everybody is on the same page? I'll handle that if you like (but it won't be until next week).

            Show
            swinbank John Swinbank added a comment - As per my earlier comment, I'm quite strongly against just using some variation on "todo" in the code to mark areas where further work is needed. I have no objection to using this in conjunction with a JIRA ticket, though. I'm actually not sure who has final say on this, though. The description of this ticket mentions "senior developers"; it may be that Kian-Tat Lim claims some jurisdiction here; and since "todo" in particular relates to tracking future work, I reckon it's particularly of relevance to T/CAMs. Maybe worth an RFC to ensure everybody is on the same page? I'll handle that if you like (but it won't be until next week).
            Hide
            krzys Krzysztof Findeisen added a comment -

            K-T will have to approve any changes to the dev guide, regardless. An RFC might be appropriate, but it would be kind of weird given that this issue is already an implementation ticket for another RFC.

            Show
            krzys Krzysztof Findeisen added a comment - K-T will have to approve any changes to the dev guide, regardless. An RFC might be appropriate, but it would be kind of weird given that this issue is already an implementation ticket for another RFC.
            krzys Krzysztof Findeisen made changes -
            Link This issue relates to RFC-307 [ RFC-307 ]
            Hide
            tjenness Tim Jenness added a comment -

            You are stuck in a maze of twisty RFCs...

            K-T will have to approve the dev guide pull request before it can be merged anyhow.

            Show
            tjenness Tim Jenness added a comment - You are stuck in a maze of twisty RFCs... K-T will have to approve the dev guide pull request before it can be merged anyhow.
            krzys Krzysztof Findeisen made changes -
            Link This issue is triggered by RFC-307 [ RFC-307 ]
            krzys Krzysztof Findeisen made changes -
            Link This issue relates to RFC-307 [ RFC-307 ]
            Hide
            krzys Krzysztof Findeisen added a comment -

            Hi Kian-Tat Lim, could you please review DM-7892 and DM-9966? These are the final changes to the dev guide needed to close RFC-225 and RFC-307, and they're fairly small updates.

            Show
            krzys Krzysztof Findeisen added a comment - Hi Kian-Tat Lim , could you please review DM-7892 and DM-9966 ? These are the final changes to the dev guide needed to close RFC-225 and RFC-307 , and they're fairly small updates.
            krzys Krzysztof Findeisen made changes -
            Reviewers Kian-Tat Lim [ ktl ]
            Status In Progress [ 3 ] In Review [ 10004 ]
            Hide
            ktl Kian-Tat Lim added a comment -

            I think the one change affecting existing practice is the @code -> indent change. Please make sure to publicize this.

            Show
            ktl Kian-Tat Lim added a comment - I think the one change affecting existing practice is the @code -> indent change. Please make sure to publicize this.
            ktl Kian-Tat Lim made changes -
            Status In Review [ 10004 ] Reviewed [ 10101 ]
            Hide
            krzys Krzysztof Findeisen added a comment -

            Merged and announced.

            Show
            krzys Krzysztof Findeisen added a comment - Merged and announced.
            krzys Krzysztof Findeisen made changes -
            Resolution Done [ 10000 ]
            Status Reviewed [ 10101 ] Done [ 10002 ]
            rhl Robert Lupton made changes -
            Labels SciencePipelines Standards dm-dev-guide documentation, SciencePipelines Standards dm-dev-guide documentation documentation,
            rhl Robert Lupton made changes -
            Link This issue has to be done after DM-7891 [ DM-7891 ]
            rhl Robert Lupton made changes -
            Labels SciencePipelines Standards dm-dev-guide documentation documentation, SciencePipelines Standards dm-dev-guide documentation

              People

              Assignee:
              krzys Krzysztof Findeisen
              Reporter:
              krzys Krzysztof Findeisen
              Reviewers:
              Kian-Tat Lim
              Watchers:
              John Swinbank, Kian-Tat Lim, Krzysztof Findeisen, Tim Jenness
              Votes:
              0 Vote for this issue
              Watchers:
              4 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved:

                  CI Builds

                  No builds found.