[26/42] qapi/parser: add undocumented stub members to all_sections

Commit Message

John Snow Feb. 5, 2025, 11:11 p.m. UTC

This helps simplify the new doc generator if it doesn't have to check
for undocumented members; especially when dealing recursively with
inherited documentation blocks.

NB: If there is no existing 'member' section, these undocumented stub
members will be inserted directly after the intro paragraph(s). This is
potentially problematic for cases where a doc block contains *only* free
paragraphs, but some of those paragraphs are conceptually better suited
for the "outro" section; i.e.:


This patch will insert member documentation after the example,
effectively solidifying all preceding paragraphs as "intro" type, which
may not be what we want.

Solution for this issue is still TBD; auditing is needed to understand
how prevalent the problem is to help engineer a fix or decide it's not
really a problem that needs solving.

While I'm rambling about RFC stuff in the commit message though, this
patch really did help cull over a hundred lines from the new generator,
so I think I'm predisposed to find a way to keep it.

Signed-off-by: John Snow <[e-mail]>
---
 scripts/qapi/parser.py | 12 ++++++++++++
 1 file changed, 12 insertions(+)

Patch

diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
index af5d7bf892c..a8b30ae1a4b 100644
--- a/scripts/qapi/parser.py
+++ b/scripts/qapi/parser.py
@@ -800,6 +800,18 @@  def connect_member(self, member: 'QAPISchemaMember') -> None:
             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: