I'm feeling dense again. Please be patient with me. John Snow <[email protected]> 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 <[email protected]> > --- > 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...]
