Merge tag 'pull-qapi-2023-04-28' of https://repo.or.cz/qemu/armbru into staging

QAPI patches patches for 2023-04-28

# -----BEGIN PGP SIGNATURE-----
#
# iQJGBAABCAAwFiEENUvIs9frKmtoZ05fOHC0AOuRhlMFAmRLlpsSHGFybWJydUBy
# ZWRoYXQuY29tAAoJEDhwtADrkYZTTjwP/iezbnBFv55HxaRFisEpBom7skXakV1r
# 0KTyYNo0BatS01yVlX7IOh37ZVmoBHrpbs0SLb2V5/uVALQBvmlnhUCCQ+BJwhJF
# JON6yjZRKUikVKn8CGj0ql9KDF6bC/T1ByFEotGc7SBMCx+FWuGXnmVzwOKOK2O3
# XAHG1P04wlxuyHMt3V7qqbc5IyzZIEHLbEitDhQM/6quQmwx4NzFR+JwvzUXCok1
# F7cEt0cKbE3JZHSXWIVTOuseeZR8vnk3giKBgFOetqhVorGusiTPMQwpDPvvgKGn
# fkg2l5SZQz9hSDfuzCKpJSQDqO8ji+62fHci9+PPpG10raoMiwCiuhP9yYECYekM
# 7BcAY7fItrUB+x+vjm8JRY15JxOT8ouHLfyknNLOwow8QwtsiNn35VlRJU7O+k+D
# gk9qvwl1RoLUSXzOo6Ye1NvzF8oMZ8o8f0vmYC+W3sdg89U9QnRrpCaX8YCytLnd
# rEXJiL26mg54yXrWShIzLvC33//sz7AvH6IjwrRt0ZQu7ANRJsNmYY9S1THAJBKW
# b9hY3Aosw8Advt0RUFkYr/PndZp/gxDpbtOCIkKZkti6XRkY89ExPk6zVmeo8miw
# DeEo1kRtzKYDC7ZU0yp73MZDSmUt17L1AfdgS0QuCQCfPHsa8LwtZoQmRIihT/Bo
# GZTLIZPiVC79
# =mkwX
# -----END PGP SIGNATURE-----
# gpg: Signature made Fri 28 Apr 2023 10:49:15 AM BST
# gpg:                using RSA key 354BC8B3D7EB2A6B68674E5F3870B400EB918653
# gpg:                issuer "armbru@redhat.com"
# gpg: Good signature from "Markus Armbruster <armbru@redhat.com>" [undefined]
# gpg:                 aka "Markus Armbruster <armbru@pond.sub.org>" [undefined]
# gpg: WARNING: This key is not certified with a trusted signature!
# gpg:          There is no indication that the signature belongs to the owner.
# Primary key fingerprint: 354B C8B3 D7EB 2A6B 6867  4E5F 3870 B400 EB91 8653

* tag 'pull-qapi-2023-04-28' of https://repo.or.cz/qemu/armbru:
  docs/devel/qapi-code-gen: Describe some doc markup pitfalls
  qapi storage-daemon/qapi: Fix documentation section structure
  qapi: Format since information the conventional way: (since X.Y)
  qapi: Fix misspelled section tags in doc comments
  qapi: Replace ad hoc "since" documentation by member documentation
  qapi: Fix argument documentation markup
  qga/qapi-schema: Fix member documentation markup
  qapi: Fix unintended definition lists in documentation
  qapi: Fix bullet list markup in documentation
  qapi: Delete largely misleading "Stability Considerations"
  qapi: Tidy up examples
  qapi: @foo should be used to reference, not ``foo``
  qapi/block-core: Clean up after removal of dirty bitmap @status
  qapi: Fix up references to long gone error classes
  qapi: Fix misspelled references
  qga/qapi-schema: Fix a misspelled reference
  qga/qapi-schema: Tidy up documentation of guest-fsfreeze-status

Signed-off-by: Richard Henderson <richard.henderson@linaro.org>

1 files changed, 59 insertions, 3 deletions

diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst
index 879a649e8c..af1986f33e 100644
--- a/docs/devel/qapi-code-gen.rst
+++ b/docs/devel/qapi-code-gen.rst
@@ -924,14 +924,17 @@ first character of the first line.
 
 The usual ****strong****, *\*emphasized\** and ````literal```` markup
 should be used.  If you need a single literal ``*``, you will need to
-backslash-escape it.  As an extension beyond the usual rST syntax, you
-can also use ``@foo`` to reference a name in the schema; this is rendered
-the same way as ````foo````.
+backslash-escape it.
+
+Use ``@foo`` to reference a name in the schema.  This is an rST
+extension.  It is rendered the same way as ````foo````, but carries
+additional meaning.
 
 Example::
 
  ##
  # Some text foo with **bold** and *emphasis*
+ #
  # 1. with a list
  # 2. like that
  #
@@ -1057,6 +1060,59 @@ For example::
    'returns': ['BlockStats'] }
 
 
+Markup pitfalls
+~~~~~~~~~~~~~~~
+
+A blank line is required between list items and paragraphs.  Without
+it, the list may not be recognized, resulting in garbled output.  Good
+example::
+
+ # An event's state is modified if:
+ #
+ # - its name matches the @name pattern, and
+ # - if @vcpu is given, the event has the "vcpu" property.
+
+Without the blank line this would be a single paragraph.
+
+Indentation matters.  Bad example::
+
+ # @none: None (no memory side cache in this proximity domain,
+ #              or cache associativity unknown)
+
+The description is parsed as a definition list with term "None (no
+memory side cache in this proximity domain," and definition "or cache
+associativity unknown)".
+
+Section tags are case-sensitive and end with a colon.  Good example::
+
+ # Since: 7.1
+
+Bad examples (all ordinary paragraphs)::
+
+ # since: 7.1
+
+ # Since 7.1
+
+ # Since : 7.1
+
+Likewise, member descriptions require a colon.  Good example::
+
+ # @interface-id: Interface ID
+
+Bad examples (all ordinary paragraphs)::
+
+ # @interface-id   Interface ID
+
+ # @interface-id : Interface ID
+
+Undocumented members are not flagged, yet.  Instead, the generated
+documentation describes them as "Not documented".  Think twice before
+adding more undocumented members.
+
+When you change documentation comments, please check the generated
+documentation comes out as intended!
+
+
 Client JSON Protocol introspection
 ==================================