Re: [PATCH v2 05/13] qapi/docs: adjust stub member insertion algorithm

[Markus Armbruster <armbru@redhat.com>]

I'm feeling dense again.  Please be patient with me.

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.

What are the stub and dummy members?

> This algorithm can handle zero-or-more PLAIN *or* INTRO sections at the
> beginning of a QAPIDoc object.

The revised algorithm, I presume.

What's the structure of its valid input before and after this patch?

> Since we have three places that need to insert stub members, take the
> opportunity to unify and deduplicate this code.

Three?  I can only see two: Transmogrifier.visit_sections() and
QAPIDoc.connect_member().

>
> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
>  docs/sphinx/qapidoc.py | 36 ++++++++---------
>  scripts/qapi/parser.py | 90 +++++++++++++++++++++++++++---------------
>  2 files changed, 75 insertions(+), 51 deletions(-)
>
> diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
> index 1f7c15b7075..70ab9cdc214 100644
> --- a/docs/sphinx/qapidoc.py
> +++ b/docs/sphinx/qapidoc.py
> @@ -349,30 +349,32 @@ def _get_target(
>                  )
>  
>      def visit_sections(self, ent: QAPISchemaDefinition) -> None:
> +        # Generate a placeholder right after the member section(s) which
> +        # will be used to generate documentation for "The members of..."
> +        # pointers in the rendered document.
> +        # This is a temporary hack until the inliner is merged.
> +        if ent.doc:
> +            ent.doc.append_member_stub(
> +                QAPIDoc.ArgSection(
> +                    ent.doc.info, QAPIDoc.Kind.MEMBER, "q_dummy"
> +                )
> +            )
> +

This hack is of the nastier sort: passing a QAPISchema to the doc
generator modifies it.

Would it be possible to add this dummy always in QAPISchema?  Any
drawbacks?

[Remainder left for later...]