Merge tag 'pull-qapi-2024-02-26' of https://repo.or.cz/qemu/armbru into staging

QAPI patches patches for 2024-02-26

# -----BEGIN PGP SIGNATURE-----
#
# iQJGBAABCAAwFiEENUvIs9frKmtoZ05fOHC0AOuRhlMFAmXcXWUSHGFybWJydUBy
# ZWRoYXQuY29tAAoJEDhwtADrkYZTMqQP/3aZ8Jm48Bh4sG5JxJ01aM3iX//cuA8X
# 0xoKBfDWkwKvUDE+sv+2qH1WxcNGS4wb/lLaT6Jf0S8EzzelDx5zYGwXXsmBljoZ
# Kh8BI7Oe1SQwI5Z36q/efG9isQ6nqGyxR9xu1BTbJCSOZXzxpOBljbSyXOtKc5C/
# HM4TK82geLLgm04gMkoPmFdu3BXDfPYnGJ3UNLE9hTPoW7XL4EGFAOOWuDcrSF5n
# OdHjfK9TK9PcxsJGqVUqLHwfRQYLMBni6OkurdFOVdLM1v4C707NuryjaGQc1WEI
# xKwsJDKR+zG7vGu4y594HN/Ivoaqci8MMTbDgVmHZ3LaI3RUfSplGTDSYLjCp8jz
# XDx82+hhmb/2ZMmE0tarUQyv0dimrZSEh6cWWHMvp63edKTywoB/eIDR9lBteTZe
# wRvkSKmN6oKJI8cNiiXZqw5y2JPvhNag4Xdr8kHKwHgxVWP+SneInLCC+T2SMgio
# EeC+S4CVTdjPvEC96dOGrsqKn+gl/h74PK5ZdTaD1B6XCuIalsRn6REujqW6Ew6n
# rj7Iec/noejeOsflzBWRKT91t2Zck/MRLhX9nYqybBxyxUFvFS7M6ok/iq4oEtZR
# lJooF6iiq8xtEzoLselfGFAZTUxhwLdUfXPVDx7p5HDpJci88xv6zmav9eE84JbH
# mBD55GEH17ka
# =81Zq
# -----END PGP SIGNATURE-----
# gpg: Signature made Mon 26 Feb 2024 09:44:05 GMT
# gpg:                using RSA key 354BC8B3D7EB2A6B68674E5F3870B400EB918653
# gpg:                issuer "armbru@redhat.com"
# gpg: Good signature from "Markus Armbruster <armbru@redhat.com>" [full]
# gpg:                 aka "Markus Armbruster <armbru@pond.sub.org>" [full]
# Primary key fingerprint: 354B C8B3 D7EB 2A6B 6867  4E5F 3870 B400 EB91 8653

* tag 'pull-qapi-2024-02-26' of https://repo.or.cz/qemu/armbru:
  qapi: Divorce QAPIDoc from QAPIParseError
  qapi: Reject multiple and empty feature descriptions
  qapi: Rewrite doc comment parser
  qapi: Merge adjacent untagged sections
  qapi: Call QAPIDoc.check() always
  qapi: Recognize section tags and 'Features:' only after blank line
  qapi: Require descriptions and tagged sections to be indented
  qapi: Reject section heading in the middle of a doc comment
  qapi: Rename QAPIDoc.Section.name to .tag
  qapi: Improve error message for empty doc sections
  qapi: Improve error position for bogus invalid "Returns" section
  qapi: Improve error position for bogus argument descriptions
  sphinx/qapidoc: Drop code to generate doc for simple union branch
  tests/qapi-schema: Cover 'Features:' not followed by descriptions
  tests/qapi-schema: Cover duplicate 'Features:' line
  tests/qapi-schema: Fix test 'QAPI rST doc'
  qapi: Misc cleanups to migrate QAPIs

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

2 files changed, 28 insertions, 30 deletions

diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst
index 756adc1..6804a4b 100644
--- a/docs/devel/qapi-code-gen.rst
+++ b/docs/devel/qapi-code-gen.rst
@@ -973,7 +973,7 @@ commands and events), member (for structs and unions), branch (for
 alternates), or value (for enums), a description of each feature (if
 any), and finally optional tagged sections.
 
-Descriptions start with '\@name:'.  The description text should be
+Descriptions start with '\@name:'.  The description text must be
 indented like this::
 
  # @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
@@ -986,19 +986,20 @@ indented like this::
 Extensions added after the definition was first released carry a
 "(since x.y.z)" comment.
 
-The feature descriptions must be preceded by a line "Features:", like
-this::
+The feature descriptions must be preceded by a blank line and then a
+line "Features:", like this::
 
+  #
   # Features:
   #
   # @feature: Description text
 
-A tagged section starts with one of the following words:
-"Note:"/"Notes:", "Since:", "Example:"/"Examples:", "Returns:",
-"TODO:".  The section ends with the start of a new section.
+A tagged section begins with a paragraph that starts with one of the
+following words: "Note:"/"Notes:", "Since:", "Example:"/"Examples:",
+"Returns:", "TODO:".  It ends with the start of a new section.
 
-The second and subsequent lines of sections other than
-"Example"/"Examples" should be indented like this::
+The second and subsequent lines of tagged sections must be indented
+like this::
 
  # Note: Ut enim ad minim veniam, quis nostrud exercitation ullamco
  #     laboris nisi ut aliquip ex ea commodo consequat.
@@ -1049,11 +1050,10 @@ For example::
  #
  # Example:
  #
- # -> { "execute": "query-blockstats" }
- # <- {
- #      ... lots of output ...
- #    }
- #
+ #     -> { "execute": "query-blockstats" }
+ #     <- {
+ #          ... lots of output ...
+ #        }
  ##
  { 'command': 'query-blockstats',
    'data': { '*query-nodes': 'bool' },
@@ -1087,8 +1087,10 @@ need to line up with each other, like this::
  #     or cache associativity unknown)
  #     (since 5.0)
 
-Section tags are case-sensitive and end with a colon.  Good example::
+Section tags are case-sensitive and end with a colon.  They are only
+recognized after a blank line.  Good example::
 
+ #
  # Since: 7.1
 
 Bad examples (all ordinary paragraphs)::
diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
index 05b809a..8d428c6 100644
--- a/docs/sphinx/qapidoc.py
+++ b/docs/sphinx/qapidoc.py
@@ -180,17 +180,13 @@ class QAPISchemaGenRSTVisitor(QAPISchemaVisitor):
 
         if variants:
             for v in variants.variants:
-                if v.type.is_implicit():
-                    assert not v.type.base and not v.type.variants
-                    for m in v.type.local_members:
-                        term = self._nodes_for_one_member(m)
-                        term.extend(self._nodes_for_variant_when(variants, v))
-                        dlnode += self._make_dlitem(term, None)
-                else:
-                    term = [nodes.Text('The members of '),
-                            nodes.literal('', v.type.doc_type())]
-                    term.extend(self._nodes_for_variant_when(variants, v))
-                    dlnode += self._make_dlitem(term, None)
+                if v.type.name == 'q_empty':
+                    continue
+                assert not v.type.is_implicit()
+                term = [nodes.Text('The members of '),
+                        nodes.literal('', v.type.doc_type())]
+                term.extend(self._nodes_for_variant_when(variants, v))
+                dlnode += self._make_dlitem(term, None)
 
         if not dlnode.children:
             return []
@@ -243,8 +239,8 @@ class QAPISchemaGenRSTVisitor(QAPISchemaVisitor):
         seen_item = False
         dlnode = nodes.definition_list()
         for section in doc.features.values():
-            dlnode += self._make_dlitem([nodes.literal('', section.name)],
-                                        section.text)
+            dlnode += self._make_dlitem(
+                [nodes.literal('', section.member.name)], section.text)
             seen_item = True
 
         if not seen_item:
@@ -262,11 +258,11 @@ class QAPISchemaGenRSTVisitor(QAPISchemaVisitor):
         """Return list of doctree nodes for additional sections"""
         nodelist = []
         for section in doc.sections:
-            if section.name and section.name == 'TODO':
+            if section.tag and section.tag == 'TODO':
                 # Hide TODO: sections
                 continue
-            snode = self._make_section(section.name)
-            if section.name and section.name.startswith('Example'):
+            snode = self._make_section(section.tag)
+            if section.tag and section.tag.startswith('Example'):
                 snode += self._nodes_for_example(section.text)
             else:
                 self._parse_text_into_node(section.text, snode)