Re: [PATCH 2/8] qapi: prohibit 'details' sections between tagged sections

[Markus Armbruster <armbru@redhat.com>]

John Snow <jsnow@redhat.com> writes:

> This patch prohibits plain documentation sections from appearing between
> "tagged" sections. The two existing uses of this pattern are patched
> out.

One real use, and one just for test coverage.

> This is being done primarily to ensure consistency between the source
> documents and the final, rendered HTML output. Because
> member/feature/returns/error sections will always appear in a visually
> grouped element in the HTML output, prohibiting plain paragraphs between
> those sections ensures ordering consistency between source and the final
> render.

Is consistency an actual problem being fixed, or a future problem being
avoided?  I'm guessing the latter, based on my review of qom.json below.

> Additionally, prohibiting such "middle" text paragraphs allows us to
> classify all plain text sections as either "intro" or "details" sections,
> because these sections must either appear before structured/tagged
> sections ("intro") or afterwards ("details").

Huh?

The previous patch already classified all plain text sections as either
INTRO or DETAILS.

I think the paragraph would make sense if this patch came before the
previous one.

> This keeps the inlining algorithm simpler with fewer "splice" points
> when merging multiple documentation blocks.
>
> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
>  qapi/qom.json                   |  4 ++--
>  scripts/qapi/parser.py          | 17 +++++++++++++++++
>  tests/qapi-schema/doc-good.json |  4 ++--
>  tests/qapi-schema/doc-good.out  |  4 ++--
>  tests/qapi-schema/doc-good.txt  |  8 ++++----
>  5 files changed, 27 insertions(+), 10 deletions(-)
>
> diff --git a/qapi/qom.json b/qapi/qom.json
> index c653248f85d..1b47abd44e9 100644
> --- a/qapi/qom.json
> +++ b/qapi/qom.json
> @@ -243,12 +243,12 @@
>  #
>  # @typename: the type name of an object
>  #
> +# Returns: a list describing object properties
> +#
>  # .. note:: Objects can create properties at runtime, for example to
>  #    describe links between different devices and/or objects.  These
>  #    properties are not included in the output of this command.
>  #
> -# Returns: a list describing object properties
> -#
>  # Since: 2.12
>  ##
>  { 'command': 'qom-list-properties',

Rendered documentation before the patch:

    Command qom-list-properties (Since: 2.12)

       List properties associated with a QOM object.

       Arguments:
          * typename (string) -- the type name of an object

       Note:

         Objects can create properties at runtime, for example to describe
         links between different devices and/or objects.  These properties
         are not included in the output of this command.

       Return:
          [ObjectPropertyInfo] -- a list describing object properties

Afterwards:

    Command qom-list-properties (Since: 2.12)

       List properties associated with a QOM object.

       Arguments:
          * typename (string) -- the type name of an object

       Return:
          [ObjectPropertyInfo] -- a list describing object properties

       Note:

         Objects can create properties at runtime, for example to describe
         links between different devices and/or objects.  These properties
         are not included in the output of this command.

Fine.

[Skipping the Python code in my first pass...]

> diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json
> index fac13425b72..9103fed472e 100644
> --- a/tests/qapi-schema/doc-good.json
> +++ b/tests/qapi-schema/doc-good.json
> @@ -165,12 +165,12 @@
>  # @cmd-feat1: a feature
>  # @cmd-feat2: another feature
>  #
> -# .. note:: @arg3 is undocumented
> -#
>  # Returns: @Object
>  #
>  # Errors: some
>  #
> +# .. note:: @arg3 is undocumented
> +#
>  # TODO: frobnicate
>  #
>  # .. admonition:: Notes
> diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out
> index 04e29e8d50f..6a0167ad580 100644
> --- a/tests/qapi-schema/doc-good.out
> +++ b/tests/qapi-schema/doc-good.out
> @@ -175,12 +175,12 @@ description starts on the same line
>  a feature
>      feature=cmd-feat2
>  another feature
> -    section=Details
> -.. note:: @arg3 is undocumented
>      section=Returns
>  @Object
>      section=Errors
>  some
> +    section=Details
> +.. note:: @arg3 is undocumented
>      section=Todo
>  frobnicate
>      section=Details

The Details section is still between tagged sections.  The code
prohibiting it must have a hole :)

> diff --git a/tests/qapi-schema/doc-good.txt b/tests/qapi-schema/doc-good.txt
> index 74b73681d32..ded699dd596 100644
> --- a/tests/qapi-schema/doc-good.txt
> +++ b/tests/qapi-schema/doc-good.txt
> @@ -120,16 +120,16 @@ Command cmd (Since: 2.10)
>  
>        * **cmd-feat2** -- another feature
>  
> -   Note:
> -
> -     "arg3" is undocumented
> -
>     Return:
>        "Object" -- "Object"
>  
>     Errors:
>        some
>  
> +   Note:
> +
> +     "arg3" is undocumented
> +
>     Notes:
>  
>     * Lorem ipsum dolor sit amet