Re: [PATCH v3 09/16] qapi/docs: adjust stub member insertion algorithm

[Markus Armbruster <armbru@redhat.com>]

Quick first pass...

John Snow <jsnow@redhat.com> writes:

> A forthcoming patch removes the implicit PLAIN section that always
> starts a QAPIDoc section list. Further future changes begin converting
> "PLAIN" sections to "INTRO" sections. To accommodate this, the
> insertion algorithm that places stub and dummy members must be
> adjusted to cope with not only the finished state, but temporary
> intermediate states while the series is merged.

Perhaps:

  A forthcoming patch removes the implicit PLAIN section that always
  starts a QAPIDoc section list. Further future changes begin converting
  "PLAIN" sections to "INTRO" sections.

  This will affect the code that inserts "Not documented" descriptions
  for undocumented members ("stub sections") and the dummy section that
  marks the spot for "The members of ..." references.

  Adjust the algorithm to cope with not only the finished state, but
  temporary intermediate states while the series is merged.

> This algorithm can handle zero-or-more PLAIN *or* INTRO sections at
> the beginning of a QAPIDoc object, in contrast to the previous
> algorithm which assumed and relied upon there being always one PLAIN
> section at the beginning of every QAPIDoc section list.
>
> In other words: (PLAIN | INTRO)* <EverythingElse>
>
> This does not impact what the parser itself will actually produce. As
> of this patch, the parser will still always generate QAPIDoc section
> lists that start with precisely one PLAIN section (whether or not it
> is empty), followed by the remaining sections. Those remaining
> sections may or may not include additional PLAIN sections, but never
> two such sections contiguously as the parser will always treat that
> layout as one PLAIN section consisting of multiple paragraph(s).
>
> In other other words: This insertion algorithm is more lenient than
> the parser, but this is on purpose for flexibility mid-stream as we
> convert QAPI to using explicit introductory sections. The allowed
> order of sections will eventually become strictly enforced in the
> parser, which will in turn allow dramatic simplifications to the
> insertion algorithm. This only exists as transitory code until we are
> able to enforce that order.
>
> Fear not: the intermediate rest output before and after this patch

"ReST output"?

> are byte identical, so failing all else, we at least know it doesn't
> make anything worse.
>
> Lastly, because we have three places in the code that need to insert
> stub/dummy sections, we take the opportunity to consolidate this code
> to handle all three cases with one function. This winds up
> necessitating the qapidoc.py generator actually modify the section
> list to insert a "dummy" member that acts as a placeholder for "The
> members of ..." text. While it looks like a code smell to modify the
> caller's argument, it is ultimately safe because the QAPI Schema
> object is re-parsed and re-constructed in memory for each individual
> process that needs to operate on it. In other words, the Sphinx
> document generator already does have "its own copy" of the section
> lists, so it is "safe" to modify here without regards to other
> consumers of the QAPIDoc objects. It only *looks* like it smells
> bad. Ultimately, this code will also be removed once the inliner is
> merged, so it is only a temporary aesthetic issue regardless.

Such trickery, even when safe, risks making attentive readers go
"WAT?!?"  I find it tolerable only because we plan to replace it fairly
soon.

The code finding the spot to insert stub/dummy sections is more
complicated than it has any right to be, both before and after your
patch.  It reconstructs information the doc parser has, but doesn't pass
on in usable form.  Passing that info on would likely be simpler and
cleaner.  However, you tell me your inliner patches also simplify
things, and they already exist.  So let's go with those.

> That's my story and I'm sticking to it.
>
> Signed-off-by: John Snow <jsnow@redhat.com>