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

Clarify role of extended description vs. notes in developer guide

    Details

    • Type: Improvement
    • Status: Done
    • Resolution: Done
    • Fix Version/s: None
    • Component/s: dm_dev_guide
    • Labels:
      None
    • Templates:
    • Story Points:
      1.8
    • Team:
      SQuaRE

      Description

      The C++ and Python documentation style guides both have an "extended description" and a "notes" section. Their descriptions (in the Python version) read:

      Extended Summary

      A few sentences giving an extended description. This section should be used to clarify functionality, not to discuss implementation detail or background theory, which should rather be explored in the ‘Notes’ section below.

      Notes

      Notes is an optional section that provides additional information about the code, possibly including a discussion of the algorithm.

      I interpreted this to mean that all descriptions of the function/method's behavior go in the Extended Summary, while the Notes are used for information that's interesting but does not affect behavior (and, like implementation details, may be non-binding).

      However, in the review for DM-16017 Jonathan Sick argued that nearly all information belongs in Notes, even if this means splitting functionality information across sections (e.g., the baseline behavior belongs in the Extended Summary, while special cases go in Notes). This does not follow from the current wording.

      Please reword the descriptions of these two sections in both the C++* and Python guides to make their relative scopes clearer, including the fact that Notes may contain important information for both callers and maintainers.

      *A complication: in C++, one of these two sections must be able to contain extended parameter discussion, because, unlike Sphinx, Doxygen doesn't support paragraph breaks in parameter documentation.

        Attachments

          Container Issues

            Issue Links

              Activity

                People

                • Assignee:
                  jsick Jonathan Sick
                  Reporter:
                  krzys Krzysztof Findeisen
                  Reviewers:
                  Kian-Tat Lim
                  Watchers:
                  Jonathan Sick, Kian-Tat Lim, Krzysztof Findeisen
                • Votes:
                  0 Vote for this issue
                  Watchers:
                  3 Start watching this issue

                  Dates

                  • Created:
                    Updated:
                    Resolved:

                    Summary Panel