[v2] docs: Add new QAPI transmogrifier

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

Posted by John Snow 3 weeks, 4 days ago

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 | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

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:
-- 
2.48.1

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

Posted by Markus Armbruster 3 weeks, 2 days ago

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 | 15 ++++++++++++++-
>  1 file changed, 14 insertions(+), 1 deletion(-)
>
> 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.

Please add

               # TODO drop when undocumented members are outlawed

> +            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: