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.