Re: [PATCH 1/8] qapi: differentiate "intro" and "details" sections

[Markus Armbruster <armbru@redhat.com>]

John Snow <jsnow@redhat.com> writes:

> This patch begins distinguishing "Plain" sections as being either
> "Intro" or "Details" sections for the purpose of knowing when/where/how
> to inline those sections.
>
> The Intro section is always the first section of any doc block. It may
> be empty or any number of paragraphs. It is interrupted by any other
> non-plaintext section, i.e.; Members, Features, Errors, Returns, Since,
> and TODO.
>
> The details section, when present, is either the last section or the
> second-to-last section when a "Since:" section is present. It consists
> of any plain text in the doc block that follows any named sections if
> present.
>
> Signed-off-by: John Snow <jsnow@redhat.com>

The commit message explains what kinds INTRO and DETAILS are, but not
why they're useful.  My guess:

1. Represent the future "Details:" marker: the plain section before it
is of kind INTRO, the one afterwards is of kind DETAILS.

2. Future programming convenience?  With just PLAIN, code may have to
understand the section's context to make decisions, and with INTRO and
DETAILS is doesn't.

Guess close enough?

The commit message covers PLAIN sections at the beginning and at the end
(modulo Since:).  It doesn't cover PLAIN sections between tagged
sections / member descriptions.  You disallow these in PATCH 2.  You can
either cover them here, or get rid of them by swapping PATCH 1 and 2.

Hmm, is your description of DETAILS accurate?  Looks like it isn't; see
my review of tests/qapi-schema/doc-good.out below.

> ---
>  docs/sphinx/qapidoc.py         |  2 +-
>  scripts/qapi/parser.py         | 35 +++++++++++++++++++++++-----------
>  tests/qapi-schema/doc-good.out |  8 ++++----
>  3 files changed, 29 insertions(+), 16 deletions(-)

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

> diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out
> index 04a55072646..04e29e8d50f 100644
> --- a/tests/qapi-schema/doc-good.out
> +++ b/tests/qapi-schema/doc-good.out
> @@ -116,7 +116,7 @@ The _one_ {and only}, description on the same line
>  Also _one_ {and only}
>      feature=enum-member-feat
>  a member feature
> -    section=Plain
> +    section=Details
>  @two is undocumented

The section containing "@two is undocumented" changes from PLAIN to
DETAILS.  Doc source:

    ##
    # @Enum:
    #
    # @one: The _one_ {and only}, description on the same line
    #
    # Features:
    # @enum-feat: Also _one_ {and only}
    # @enum-member-feat: a member feature
    #
    # @two is undocumented
    ##

It is at the end.  Good.

>  doc symbol=Base
>      body=
> @@ -175,7 +175,7 @@ description starts on the same line
>  a feature
>      feature=cmd-feat2
>  another feature
> -    section=Plain
> +    section=Details
>  .. note:: @arg3 is undocumented

The section containing "@arg3 is undocumented" changes from PLAIN to
DETAILS.  Doc source:

Doc source:

    ##
    # @cmd:
    #
    # @arg1:
    #     description starts on a new line,
    #     indented
    #
    # @arg2: description starts on the same line
    #     remainder indented differently
    #
    # Returns: @Object
    #
    # Errors: some
    #
    # Features:
    # @cmd-feat1: a feature
    # @cmd-feat2: another feature
    #
    # .. note:: @arg3 is undocumented
    #
    # TODO: frobnicate
    #

It is *not* at the end.  Is the commit message inaccurate?

>      section=Returns
>  @Object
> @@ -183,7 +183,7 @@ another feature
>  some
>      section=Todo
>  frobnicate
> -    section=Plain
> +    section=Details
>  .. admonition:: Notes
>  
>   - Lorem ipsum dolor sit amet
    - Ut enim ad minim veniam

    [some section body text elided for brevity...]

   Note::
       Ceci n'est pas une note
       section=Since
   2.10

The section starting with the adminition and ending after "Ceci n'est
pas une note" changes from PLAIN to DETAILS.  Doc source continued:

    # .. admonition:: Notes
    #
    #  - Lorem ipsum dolor sit amet
    #  - Ut enim ad minim veniam
    #
    [same text elided...]
    #
    # Note::
    #     Ceci n'est pas une note
    #
    # Since: 2.10
    ##

It is second-to-last, and the last section is SINCE.  Good.

> @@ -216,7 +216,7 @@ If you're bored enough to read this, go see a video of boxed cats
>  a feature
>      featurec=md-feat2
>  another feature
> -    section=Plain
> +    section=Details
>  .. qmp-example::
>  
>     -> "this example"

This one is also at the end.  Good.