[v2,59/62] qapi/parser: add undocumented stub members to all_sections

Commit Message

John Snow March 9, 2025, 8:35 a.m. UTC

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 <[e-mail]>
---
 scripts/qapi/parser.py | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

Patch

diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
index 11c11bb09e5..58cb9f41ae8 100644
--- a/scripts/qapi/parser.py
+++ b/scripts/qapi/parser.py
@@ -789,8 +789,21 @@  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.
+            # 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: