Give the introductory section its own small treatment. Without going into details about the as-yet-unmerged inliner, I struggle to describe precisely how the intro should be used and what types of documentation are better suited for Details. This is my attempt.
I find PEP 257 https://peps.python.org/pep-0257/#one-line-docstrings to have very good advice on what should appear in a doc summary line, but did not want to reference it directly in our specification. Signed-off-by: John Snow <[email protected]> --- docs/devel/qapi-code-gen.rst | 27 ++++++++++++++++++++++----- 1 file changed, 22 insertions(+), 5 deletions(-) diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index febe8af49f9..4932dd35b64 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -985,13 +985,30 @@ When documentation is required (see pragma_ 'doc-required'), every definition must have documentation. Definition documentation starts with a description naming the -definition with an optional indented overview, :ref:`descriptions -<doc-descrip>` of each argument (for commands and events), member (for -structs and unions), branch (for alternates), or value (for enums), -:ref:`feature descriptions <doc-feat>` of each feature (if any), and -finally optional tagged sections. +definition with an optional indented overview (the :ref:`doc-intro`), +:ref:`descriptions <doc-descrip>` of each argument (for commands and +events), member (for structs and unions), branch (for alternates), or +value (for enums), :ref:`feature descriptions <doc-feat>` of each +feature (if any), and finally optional tagged sections. +.. _doc-intro: + +Intro +^^^^^ + +The Intro section names the symbol being defined and is optionally +followed by an indented brief summary or overview of the definition. + +The intro section *may* consist of multiple indented paragraphs, but +is ideally a single summary line that does not repeat type +information or reference individual arguments/members/et al:: + + ## + # @query-block-jobs: + # Return information about long-running block device operations. + # + .. _doc-descrip: -- 2.55.0
