While grouping Features and Argument descriptions together is syntactically elegant, it is more helpful to document how a QAPI definition documentation block is laid out from start to finish.
Break apart and re-order the documentation for each section into a logical order that follows the document flow. Add cross-references and revise the documentation as we go. Note that as of this commit, we do not enforce a total section ordering for source documentation, but the order in which these sections are being presented matches the order we wish to enforce in a forthcoming commit: 1. Intro 2. Members/Arguments/etc 3. Returns 4. Errors 5. Features 6. Details 7. Since X. TODO (Not rendered or ordered.) Signed-off-by: John Snow <[email protected]> --- docs/devel/qapi-code-gen.rst | 110 ++++++++++++++++++++++++++++------- 1 file changed, 90 insertions(+), 20 deletions(-) diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index b1cc5b5f0db..3ac1c2dae18 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -985,13 +985,23 @@ 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, a description of each -argument (for commands and events), member (for structs and unions), -branch (for alternates), or value (for enums), a description of each -feature (if any), and finally optional tagged sections. +definition with an optional indented overview (the "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 :ref:`tagged sections +<doc-tagged>`. -Descriptions start with '\@name:'. The description text must be -indented like this:: +.. _doc-descrip: + +Descriptions +^^^^^^^^^^^^ + +Descriptions start with '\@name:'. These are used to document +arguments (for commands and events), members (for structs and unions), +branches (for alternates), or values (for enums). + +The description text must be indented like this:: # @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed # do eiusmod tempor incididunt ut labore et dolore magna aliqua. @@ -1001,15 +1011,12 @@ indented like this:: .. FIXME union branches should be described, too. Extensions added after the definition was first released carry a -"(since x.y.z)" comment. +"(since x.y)" comment. -The feature descriptions must be preceded by a blank line and then a -line "Features:", like this:: +.. _doc-tagged: - # - # Features: - # - # @feature: Description text +Tagged sections +^^^^^^^^^^^^^^^ A tagged section begins with a paragraph that starts with one of the following words: "Since:", "Returns:", "Errors:", "TODO:". It ends with @@ -1024,8 +1031,29 @@ like this:: # Duis aute irure dolor in reprehenderit in voluptate velit esse # cillum dolore eu fugiat nulla pariatur. -"Returns" and "Errors" sections are only valid for commands. They -document the success and the error response, respectively. + +Returns +^^^^^^^ + +"Returns" :ref:`doc-tagged` are only valid for commands. They document the +success response of the command. If there is some nuance to capture +with the return value, it may be documented as:: + + # + # Returns: eBPF object encoded in base64. Long lines should be + # wrapped and indented. + # + +The type of the return value will be added to the documentation +automatically. If there is nothing relevant to add apart from type, +this section may be omitted. + + +Errors +^^^^^^ + +"Errors" :ref:`doc-tagged` are only valid for commands. They document +the error responses. "Errors" sections should be formatted as an rST list, each entry detailing a relevant error condition. For example:: @@ -1034,12 +1062,33 @@ detailing a relevant error condition. For example:: # - If @device does not exist, DeviceNotFound # - Any other error returns a GenericError. -A "Since: x.y.z" tagged section lists the release that introduced the -definition. -"TODO" sections are not rendered (they are for developers, not users of -QMP). In other sections, the text is formatted, and rST markup can be -used. +.. _doc-feat: + +Feature Descriptions +^^^^^^^^^^^^^^^^^^^^ + +Feature descriptions are a :ref:`doc-descrip` section that document features +that apply to this definition. + +The feature descriptions must be preceded by a blank line and then a +line "Features:", like this:: + + # + # Features: + # + # @feature: Description text + + +Details +^^^^^^^ + +Details sections are comprised of one or more paragraphs of rST +formatted text, but otherwise are not marked up in any specific +way. In general, this text contains in-depth explanations of the +definition being documented and may include various rST admonitions +like ``.. seealso::``, ``.. note::``, etc. This is also the section +where QMP usage examples should be placed. QMP Examples can be added by using the ``.. qmp-example::`` directive. In its simplest form, this can be used to contain a single QMP code @@ -1089,6 +1138,27 @@ Highlighting in non-QMP languages can be accomplished by using the achieved by omitting the language argument. +Tagged section: Since +^^^^^^^^^^^^^^^^^^^^^ + +A "Since: x.y" :ref:`doc-tagged` lists the release that introduced the +definition:: + + # + # Since: 11.2 + # + + +TODO +^^^^ + +"TODO" tagged sections are not rendered (they are for developers, not users of +QMP). + + +Putting it all together +^^^^^^^^^^^^^^^^^^^^^^^ + Examples of complete definition documentation:: ## -- 2.55.0
