On Fri, Mar 7, 2025 at 7:25 AM Markus Armbruster <arm...@redhat.com> wrote:
> John Snow <js...@redhat.com> writes:
>
> > This method is used for generating the "members" of a wide variety of
> > things, including structs, unions, enums, alternates, etc. The field
> > name it uses to do so is dependent on the type of entity the "member"
> > belongs to.
> >
> > Signed-off-by: John Snow <js...@redhat.com>
> > ---
> > docs/sphinx/qapidoc.py | 27 +++++++++++++++++++++++++++
> > 1 file changed, 27 insertions(+)
> >
> > diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
> > index 6458790fe55..ed0269af27d 100644
> > --- a/docs/sphinx/qapidoc.py
> > +++ b/docs/sphinx/qapidoc.py
> > @@ -78,6 +78,16 @@
> >
> >
> > class Transmogrifier:
> > + # Field names used for different entity types:
> > + field_types = {
> > + "enum": "value",
> > + "struct": "memb",
> > + "union": "memb",
> > + "event": "memb",
> > + "command": "arg",
> > + "alternate": "choice",
> > + }
> > +
> > def __init__(self) -> None:
> > self._curr_ent: Optional[QAPISchemaDefinition] = None
> > self._result = StringList()
> > @@ -88,6 +98,10 @@ def entity(self) -> QAPISchemaDefinition:
> > assert self._curr_ent is not None
> > return self._curr_ent
> >
> > + @property
> > + def member_field_type(self) -> str:
> > + return self.field_types[self.entity.meta]
> > +
> > # General-purpose rST generation functions
> >
> > def get_indent(self) -> str:
> > @@ -202,6 +216,19 @@ def visit_paragraph(self, section: QAPIDoc.Section)
> -> None:
> > self.add_lines(section.text, section.info)
> > self.ensure_blank_line()
> >
> > + def visit_member(self, section: QAPIDoc.ArgSection) -> None:
> > + # TODO: ifcond for members
>
> Similar issues elsewhere are marked FIXME.
>
> Worth mentioning in the commit message?
>
Will change, and yes.
>
>
> > + # TODO?: features for members (documented at entity-level,
> > + # but sometimes defined per-member. Should we add such
> > + # information to member descriptions when we can?)
>
> I guess the '?' in 'TODO?' is there because you're not sure there's
> anything to be done about member features. But you phrased the TODO as
> a question. That makes the uncertainty obvious enough, doesn't it?
> Suggest to delete the '?' so a grep for 'TODO:' isn't deceived. Best to
> grep just for 'TODO', of course.
>
Obie-kaybie.
>
> > + assert section.text and section.member
> > + self.generate_field(
> > + self.member_field_type,
> > + section.member,
> > + section.text,
> > + section.info,
> > + )
> > +
> > def visit_feature(self, section: QAPIDoc.ArgSection) -> None:
> > # FIXME - ifcond for features is not handled at all yet!
> > # Proposal: decorate the right-hand column with some graphical
>
>
