diff options
| author | John Snow <jsnow@redhat.com> | 2025-03-10 23:42:57 -0400 |
|---|---|---|
| committer | Markus Armbruster <armbru@redhat.com> | 2025-03-11 10:26:52 +0100 |
| commit | 4d7d30b405a16d85ede6184595e8001fe2c412c4 (patch) | |
| tree | a83c9a7c5b698744639528ea921def93622ab858 /scripts/qapi | |
| parent | 565274da10fe46bf8c30a8175e39753e4fedb60e (diff) | |
| download | qemu-4d7d30b405a16d85ede6184595e8001fe2c412c4.zip qemu-4d7d30b405a16d85ede6184595e8001fe2c412c4.tar.gz qemu-4d7d30b405a16d85ede6184595e8001fe2c412c4.tar.bz2 | |
qapi/parser: add undocumented stub members to all_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.
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.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-60-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Commit message rewritten]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Diffstat (limited to 'scripts/qapi')
| -rw-r--r-- | scripts/qapi/parser.py | 17 |
1 files changed, 16 insertions, 1 deletions
diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index 11c11bb..949d9e8 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -789,8 +789,23 @@ class QAPIDoc: raise QAPISemError(member.info, "%s '%s' lacks documentation" % (member.role, member.name)) - self.args[member.name] = QAPIDoc.ArgSection( + # Insert stub documentation section for missing member docs. + # TODO: drop when undocumented members are outlawed + + section = QAPIDoc.ArgSection( self.info, QAPIDoc.Kind.MEMBER, member.name) + self.args[member.name] = section + + # 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: |