John Snow <[email protected]> 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 <[email protected]>
> ---
> 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
