Re: [PATCH v2 00/44] qapi: convert trivial intro sections

[Markus Armbruster <armbru@redhat.com>]

John Snow <jsnow@redhat.com> writes:

> GitLab CI: https://gitlab.com/jsnow/qemu/-/pipelines/2699067787
>
> Hi, this patchset converts trivial "introductory" sections in the QAPI
> documentation to use the new, explicit intro section syntax.
>
> This is being done primarily for the benefit of the forthcoming
> "inliner", a feature for the rendered HTML QMP documentation that
> seeks to "inline" QMP command argument documentation into the argument
> list for each command.
>
> There are two main motives here:
>
> (1) We want the split between the "introduction" and "details"
>     sections to be mechanically obvious, so that auto-generated or
>     inlined documentation has a well-defined, obvious spot to go.
>
> (2) We do not want to inline irrelevant, introductory text describing
>     structures to be copied into command documentation.

docs/devel/qapi-code-gen.rst until recently:

    Definition documentation starts with a line naming the definition,
    followed by an optional 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.

Recent commit ebb49d4bb6 (qapi: add doc comment "Intro" section parsing)
changed it to

    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.

It didn't actually update the schema for this change.  This series does,
but only where it's "trivial":

> This patchset tackles "trivial" conversions: cases where the
> introduction is only a single paragraph and is immediately followed by
> a tagged section, the end of the documentation block, or some other
> pre-existing syntactical delineation.

I see the following right after conversions:

* A member description "# @name: ..."

* A "Features:" line

* A tagged section like "Returns: ...", "Since: ..."

End of documentation block ("##") also makes sense, but doesn't actually
occur, because we always have a Since: somewhere after the first
paragraph.

Converting single first paragraps is mechanical.  For it to be correct,
this single paragraph must actually be the overview, and not some other
crap.  I expect it to be almost always overview.  Not sure how to best
look for the exceptions.

When there's more than one paragraph, it could still all be overview.
But the risk of "other crap" is higher.  For instance:

    ##
    # @SecretProperties:
    #
    # Properties for secret objects.
    #
    # Either @data or @file must be provided, but not both.
    #
    # @data: the associated with the secret from
    #
    # @file: the filename to load the data associated with the secret from
    #
    # Since: 2.6
    ##

Two paragraphs, only the first is "overview".

That's why you leave checking and disentangling multiple paragraphs for
later.  Makes sense.

> Future patches that may require more scrutiny will handle the
> remaining conversions - I think this is enough for today, don't you?

Oh yes, it is.