Re: [PATCH v3 00/43] qapi: convert (very) trivial intro sections

[Markus Armbruster <armbru@redhat.com>]

John Snow <jsnow@redhat.com> writes:

> v3:
>    As per Markus' request, the intro section conversion has been split
>    even further into the *very* trivial; leaving the semi-trivial and
>    not-trivial conversions for later consideration.
>
>    If you are a non-qapi/non-docs maintainer being CC'd on this patch,
>    there is **very likely** nothing for you to do here; we are only
>    changing spacing and syntax, but not modifying content in any way
>    in this series in particular. Please feel free to mark-as-read and
>    move on with your day.
> -
>
> 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.
>
> This patchset tackles "very trivial" conversions: cases where the
> existing leading plaintext is only a single sentence and is
> immediately followed by a tagged section, the end of the documentation
> block, or some other pre-existing syntactical delineation. (i.e.: not
> more plaintext.)

I checked whether the converted intros are indeed all "very trivial".
Only a few that aren't have crept in.  I replied to the patches.

I eye-balled whether these intros actually contain only introductory
text.  Looks like it (but I'm only human, and the checking is
t-e-d-i-o-u-s).  Many of them could use polish.  Not today.

With the few conversions that aren't "very trivial" dropped, series
Reviewed-by: Markus Armbruster <armbru@redhat.com>

> NOTE: This series *may* miss some conversions; future QAPI changes will
> enforce the new syntax and any cases that have appeared since v1 will
> be identified and corrected at that time; we are concerned with the
> bulk and ease-of-review here, not completeness. This is precisely why
> the new intro syntax and parser were carefully designed to allow
> gradual conversion.

Partial conversion is undesirable.  We need to finish the job.  We'll
need more than one series to have a chance at actually reviewing it.
I'm debating whether to keep them on a branch until we finish.

If I count correctly, roughly 70% of all intros are "very trivial".
Good to get them out of the way.

> NOTE2: Future patches that may require more scrutiny will handle the
> remaining conversions - There are some very subtle concerns that are
> not readily apparent in the very minor textual changes that will be
> spelled out for reviewers in the cover letters for those series.
>
> This is enough for today, don't you think?

Yes!