| Message ID | 20250311034303.75779-60-jsnow@redhat.com (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | docs: Add new QAPI transmogrifier | expand |
John Snow <jsnow@redhat.com> writes: > This helps simplify the new doc generator if it doesn't have to check > for undocumented members, it can just blindly operate on a sequence of > QAPIDoc.Section instances. > > NB: If there is no existing 'member' section, these undocumented stub > members will be inserted directly after the leading section. > > Signed-off-by: John Snow <jsnow@redhat.com> > --- > scripts/qapi/parser.py | 17 ++++++++++++++++- > 1 file changed, 16 insertions(+), 1 deletion(-) > > diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py > index 11c11bb09e5..52bc44facf2 100644 > --- a/scripts/qapi/parser.py > +++ b/scripts/qapi/parser.py > @@ -789,8 +789,23 @@ def connect_member(self, member: 'QAPISchemaMember') -> None: > raise QAPISemError(member.info, > "%s '%s' lacks documentation" > % (member.role, member.name)) > - self.args[member.name] = QAPIDoc.ArgSection( > + section = QAPIDoc.ArgSection( > self.info, QAPIDoc.Kind.MEMBER, member.name) > + self.args[member.name] = section > + > + # Insert stub documentation section for missing member docs. > + # TODO: drop when undocumented members are outlawed > + > + # Determine where to insert stub doc - it should go at the > + # end of the members section(s), if any. Note that index 0 > + # is assumed to be an untagged intro section, even if it is > + # empty. > + index = 1 > + if len(self.all_sections) > 1: > + while self.all_sections[index].kind == QAPIDoc.Kind.MEMBER: > + index += 1 > + self.all_sections.insert(index, section) > + > self.args[member.name].connect(member) > > def connect_feature(self, feature: 'QAPISchemaFeature') -> None: Reviewed-by: Markus Armbruster <armbru@redhat.com>
Markus Armbruster <armbru@redhat.com> writes: > John Snow <jsnow@redhat.com> writes: > >> This helps simplify the new doc generator if it doesn't have to check >> for undocumented members, it can just blindly operate on a sequence of >> QAPIDoc.Section instances. >> >> NB: If there is no existing 'member' section, these undocumented stub >> members will be inserted directly after the leading section. >> >> Signed-off-by: John Snow <jsnow@redhat.com> This doesn't affect the output. It's not obvious why. The old doc generator processes doc.body, .args, .features, .sections. .sections has all sections not in the other three. It does not use .all_sections. The new doc generator processes doc.all_sections. It does not use .body, .args, .features, .sections. Parser and doc generator cooperate on generating stub documentation for undocumented members. The parser makes up an ArgSection with an empty description, and the doc generator makes up a description. The old doc generator needs the made-up ArgSections in .args. The new one needs it in .all_sections. >> --- >> scripts/qapi/parser.py | 17 ++++++++++++++++- >> 1 file changed, 16 insertions(+), 1 deletion(-) >> >> diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py >> index 11c11bb09e5..52bc44facf2 100644 >> --- a/scripts/qapi/parser.py >> +++ b/scripts/qapi/parser.py >> @@ -789,8 +789,23 @@ def connect_member(self, member: 'QAPISchemaMember') -> None: if self.symbol not in member.info.pragma.documentation_exceptions: >> raise QAPISemError(member.info, >> "%s '%s' lacks documentation" >> % (member.role, member.name)) The code above rejects missing documentation unless permitted by a pragma. The code below makes up for missing documentation. [*] >> - self.args[member.name] = QAPIDoc.ArgSection( >> + section = QAPIDoc.ArgSection( >> self.info, QAPIDoc.Kind.MEMBER, member.name) >> + self.args[member.name] = section This puts the aforementioned made-up ArgSection into .args. The patch doesn't change behavior. >> + >> + # Insert stub documentation section for missing member docs. >> + # TODO: drop when undocumented members are outlawed I'm going to move this comment up to [*]. >> + >> + # Determine where to insert stub doc - it should go at the >> + # end of the members section(s), if any. Note that index 0 >> + # is assumed to be an untagged intro section, even if it is >> + # empty. >> + index = 1 >> + if len(self.all_sections) > 1: >> + while self.all_sections[index].kind == QAPIDoc.Kind.MEMBER: >> + index += 1 >> + self.all_sections.insert(index, section) This puts it into .all_sections. >> + >> self.args[member.name].connect(member) >> >> def connect_feature(self, feature: 'QAPISchemaFeature') -> None: I'm going to clarify the commit message as follows: Parser and doc generator cooperate on generating stub documentation for undocumented members. The parser makes up an ArgSection with an empty description, and the doc generator makes up a description. Right now, the made-up ArgSections go into doc.args. However, the new doc generator uses .all_sections, not .args. So put them into .all_sections, too. Insert them right after existing 'member' sections. If there are none, insert directly after the leading section. Doesn't affect the old generator, because that one doesn't use .all_sections. > Reviewed-by: Markus Armbruster <armbru@redhat.com> With that, my R-by stands.
diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index 11c11bb09e5..52bc44facf2 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -789,8 +789,23 @@ def connect_member(self, member: 'QAPISchemaMember') -> None: raise QAPISemError(member.info, "%s '%s' lacks documentation" % (member.role, member.name)) - self.args[member.name] = QAPIDoc.ArgSection( + section = QAPIDoc.ArgSection( self.info, QAPIDoc.Kind.MEMBER, member.name) + self.args[member.name] = section + + # Insert stub documentation section for missing member docs. + # TODO: drop when undocumented members are outlawed + + # Determine where to insert stub doc - it should go at the + # end of the members section(s), if any. Note that index 0 + # is assumed to be an untagged intro section, even if it is + # empty. + index = 1 + if len(self.all_sections) > 1: + while self.all_sections[index].kind == QAPIDoc.Kind.MEMBER: + index += 1 + self.all_sections.insert(index, section) + self.args[member.name].connect(member) def connect_feature(self, feature: 'QAPISchemaFeature') -> None:
This helps simplify the new doc generator if it doesn't have to check for undocumented members, it can just blindly operate on a sequence of QAPIDoc.Section instances. NB: If there is no existing 'member' section, these undocumented stub members will be inserted directly after the leading section. Signed-off-by: John Snow <jsnow@redhat.com> --- scripts/qapi/parser.py | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-)