Skip to contentSkip to conversation

qapi: Reformat doc comments

PATCH In review Markus Armbruster 4 participants 48 messages Apr 28, 2023 – May 10, 2023 Arm/Amlogic Meson SoC support

lore
Share & tools
lore
#0 lore raw

cover qapi: Reformat doc comments

This series improves the doc comment formatting rules, then reformats doc comments to conform to them.

I don't like reformatting code. But I'm tired of looking at ugly doc comments. People imitate them in new work (not blaming them for that), which leads to tiresome arguments about style. I've come to the conclusion that reformatting them is the lesser evil.

Prior discussion:

    qapi: [RFC] Doc comment convention for @arg: sections
    Message-ID: <[email protected]>
    https://lists.gnu.org/archive/html/qemu-devel/2023-03/msg05921.html

PATCH 01-12 are preliminary fixes, cleanups and test improvements, ranging from losely related to not related at all.

PATCH 13-14 improve the QAPI generator to support the style I want.

PATCH 15 writes it down.

PATCH 16-17 reformat the doc comments to conform to it.

Markus Armbruster (17):
docs/devel/qapi-code-gen: Clean up use of quotes a bit docs/devel/qapi-code-gen: Turn FIXME admonitions into comments
qapi: Fix crash on stray double quote character
meson: Fix to make QAPI generator output depend on main.py Revert "qapi: BlockExportRemoveMode: move comments to TODO" sphinx/qapidoc: Do not emit TODO sections into user manuals
qapi: Tidy up a slightly awkward TODO comment qapi/dump: Indent bulleted lists consistently tests/qapi-schema/doc-good: Improve a comment tests/qapi-schema/doc-good: Improve argument description tests
qapi: Fix argument description indentation stripping
qapi: Rewrite parsing of doc comment section symbols and tags
qapi: Relax doc string @name: description indentation rules
qapi: Section parameter @indent is no longer used, drop docs/devel/qapi-code-gen: Update doc comment conventions qga/qapi-schema: Reformat doc comments to conform to current
conventions
qapi: Reformat doc comments to conform to current conventions

 docs/devel/qapi-code-gen.rst          |   74 +-
 docs/sphinx/qapidoc.py                |    3 +
 meson.build                           |    2 +-
 qapi/acpi.json                        |   50 +-
 qapi/audio.json                       |   85 +-
 qapi/authz.json                       |   29 +-
 qapi/block-core.json                  | 2801 +++++++++++++------------
 qapi/block-export.json                |  244 ++-
 qapi/block.json                       |  214 +-
 qapi/char.json                        |  134 +-
 qapi/common.json                      |   19 +-
 qapi/compat.json                      |   13 +-
 qapi/control.json                     |   59 +-
 qapi/crypto.json                      |  261 ++-
 qapi/cryptodev.json                   |    3 +
 qapi/cxl.json                         |   74 +-
 qapi/dump.json                        |   78 +-
 qapi/error.json                       |    6 +-
 qapi/introspect.json                  |   89 +-
 qapi/job.json                         |  139 +-
 qapi/machine-target.json              |  303 +--
 qapi/machine.json                     |  389 ++--
 qapi/migration.json                   | 1120 +++++-----
 qapi/misc-target.json                 |   67 +-
 qapi/misc.json                        |  180 +-
 qapi/net.json                         |  260 ++-
 qapi/pci.json                         |   35 +-
 qapi/qapi-schema.json                 |   25 +-
 qapi/qdev.json                        |   63 +-
 qapi/qom.json                         |  404 ++--
 qapi/rdma.json                        |    1 -
 qapi/replay.json                      |   48 +-
 qapi/rocker.json                      |   20 +-
 qapi/run-state.json                   |  215 +-
 qapi/sockets.json                     |   50 +-
 qapi/stats.json                       |   83 +-
 qapi/tpm.json                         |   20 +-
 qapi/trace.json                       |   34 +-
 qapi/transaction.json                 |   87 +-
 qapi/ui.json                          |  435 ++--
 qapi/virtio.json                      |   84 +-
 qapi/yank.json                        |   42 +-
 qga/qapi-schema.json                  |  668 +++---
 scripts/qapi/parser.py                |  137 +-
 tests/qapi-schema/doc-bad-indent.err  |    2 +-
 tests/qapi-schema/doc-bad-indent.json |    3 +-
 tests/qapi-schema/doc-good.json       |   20 +-
 tests/qapi-schema/doc-good.out        |   19 +-
 48 files changed, 4822 insertions(+), 4369 deletions(-)
Signature · 1 line
2.39.2
#1 lore raw

PATCH 1/17 docs/devel/qapi-code-gen: Clean up use of quotes a bit

Section "Definition documentation" uses both single and double quotes around doc text snippets. Stick to double quotes.

---
 docs/devel/qapi-code-gen.rst | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)
docs/devel/qapi-code-gen.rst +6 -6
index af1986f33e..289869c53b 100644
@@ -989,7 +989,7 @@ The number of spaces between the ':' and the text is not significant.
    union branches should be described, too.
 
 Extensions added after the definition was first released carry a
-'(since x.y.z)' comment.
+"(since x.y.z)" comment.
 
 The feature descriptions must be preceded by a line "Features:", like
 this::
@@ -1003,17 +1003,17 @@ The section ends with the start of a new section.
 
 The text of a section can start on a new line, in
 which case it must not be indented at all.  It can also start
-on the same line as the 'Note:', 'Returns:', etc tag.  In this
+on the same line as the "Note:", "Returns:", etc tag.  In this
 case if it spans multiple lines then second and subsequent
 lines must be indented to match the first, in the same way as
 multiline argument descriptions.
 
-A 'Since: x.y.z' tagged section lists the release that introduced the
+A "Since: x.y.z" tagged section lists the release that introduced the
 definition.
 
-An 'Example' or 'Examples' section is automatically rendered
-entirely as literal fixed-width text.  In other sections,
-the text is formatted, and rST markup can be used.
+An "Example" or "Examples" section is automatically rendered entirely
+as literal fixed-width text.  In other sections, the text is
+formatted, and rST markup can be used.
 
 For example::
 
Signature · 1 line
2.39.2
#3 lore raw

PATCH 2/17 docs/devel/qapi-code-gen: Turn FIXME admonitions into comments

In reply to Markus Armbruster

We have two FIXME notes. These FIXMEs are for QAPI developers. They are not useful for QAPI schema developers. They are marked up as admonitions, which makes them look important in generated HTML.

Turn them into comments. QAPI developers will still see them (they read and write the .rst). QAPI schema developers may still see them (if they read the .rst instead of the generated .html), but "this is just for QAPI developers" should be more obvious.

---
 docs/devel/qapi-code-gen.rst | 9 ++-------
 1 file changed, 2 insertions(+), 7 deletions(-)
docs/devel/qapi-code-gen.rst +2 -7
index 289869c53b..ff7b74bdb2 100644
@@ -979,14 +979,9 @@ description::
  #          in the second style.
 
 The number of spaces between the ':' and the text is not significant.
+.. FIXME The parser accepts these things in almost any order.
 
-.. admonition:: FIXME
-
-   The parser accepts these things in almost any order.
-
-.. admonition:: FIXME
-
-   union branches should be described, too.
+.. FIXME union branches should be described, too.
 
 Extensions added after the definition was first released carry a
 "(since x.y.z)" comment.
Signature · 1 line
2.39.2
Reviewed-by on v1 2/17
#4 lore raw

Re: [PATCH 02/17] docs/devel/qapi-code-gen: Turn FIXME admonitions into comments

Quoted 10 lines · Markus Armbruster

We have two FIXME notes. These FIXMEs are for QAPI developers. They are not useful for QAPI schema developers. They are marked up as admonitions, which makes them look important in generated HTML.

Turn them into comments. QAPI developers will still see them (they read and write the .rst). QAPI schema developers may still see them (if they read the .rst instead of the generated .html), but "this is just for QAPI developers" should be more obvious.

#5 lore raw

PATCH 3/17 qapi: Fix crash on stray double quote character

In reply to Markus Armbruster

When the lexer chokes on a stray character, its shows the characters until the next structural character in the error message. It uses a regular expression to match a non-empty string of non-structural characters. Bug: the regular expression treats '"' as structural. When the lexer chokes on '"', the match fails, and trips must_match()'s assertion. Fix the regular expression.

Fixes 14c32795024c (qapi: Improve reporting of lexical errors)
---
 scripts/qapi/parser.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
scripts/qapi/parser.py +1 -1
index 878f90b458..7b49d3ab05 100644
@@ -346,7 +346,7 @@ def accept(self, skip_comment: bool = True) -> None:
             elif not self.tok.isspace():
                 # Show up to next structural, whitespace or quote
                 # character
-                match = must_match('[^[\\]{}:,\\s\'"]+',
+                match = must_match('[^[\\]{}:,\\s\']+',
                                    self.src[self.cursor-1:])
                 raise QAPIParseError(self, "stray '%s'" % match.group(0))
 
Signature · 1 line
2.39.2
Reviewed-by on v1 3/17
#6 lore raw

Re: [PATCH 03/17] qapi: Fix crash on stray double quote character

Quoted 2 lines · Markus Armbruster

When the lexer chokes on a stray character, its shows the characters until the next structural character in the error message.

You have a problem

Quoted 1 line

It uses a regular expression

You use regular expresions.

Now you have two problems.

Yes, I had to do it.

Quoted 7 lines

to match a non-empty string of non-structural characters. Bug: the regular expression treats '"' as structural. When the lexer chokes on '"', the match fails, and trips must_match()'s assertion. Fix the regular expression.

Fixes 14c32795024c (qapi: Improve reporting of lexical errors)
#7 lore raw

Re: [PATCH 03/17] qapi: Fix crash on stray double quote character

Quoted 6 lines · Juan Quintela
Quoted 2 lines · Markus Armbruster

When the lexer chokes on a stray character, its shows the characters until the next structural character in the error message.

You have a problem

Quoted 7 lines
Quoted 1 line

It uses a regular expression

You use regular expresions.

Now you have two problems.

Yes, I had to do it.

:)

Regular expressions go bad when pushed too far.

Lexers are a perfect fit for them. However, the bug I fix here isn't in the lexer proper, it's in "make the error message nice" code.

Quoted 9 lines
Quoted 7 lines

to match a non-empty string of non-structural characters. Bug: the regular expression treats '"' as structural. When the lexer chokes on '"', the match fails, and trips must_match()'s assertion. Fix the regular expression.

Fixes 14c32795024c (qapi: Improve reporting of lexical errors)

Thanks!

#8 lore raw

PATCH 4/17 meson: Fix to make QAPI generator output depend on main.py

In reply to Markus Armbruster

@qapi_gen_depends is missing scripts/qapi/main.py. Fix that, and drop a duplicate scripts/qapi/common.py.

---
 meson.build | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
meson.build +1 -1
index c44d05a13f..ed24df2ade 100644
@@ -2834,12 +2834,12 @@ qapi_gen_depends = [ meson.current_source_dir() / 'scripts/qapi/__init__.py',
                      meson.current_source_dir() / 'scripts/qapi/expr.py',
                      meson.current_source_dir() / 'scripts/qapi/gen.py',
                      meson.current_source_dir() / 'scripts/qapi/introspect.py',
+                     meson.current_source_dir() / 'scripts/qapi/main.py',
                      meson.current_source_dir() / 'scripts/qapi/parser.py',
                      meson.current_source_dir() / 'scripts/qapi/schema.py',
                      meson.current_source_dir() / 'scripts/qapi/source.py',
                      meson.current_source_dir() / 'scripts/qapi/types.py',
                      meson.current_source_dir() / 'scripts/qapi/visit.py',
-                     meson.current_source_dir() / 'scripts/qapi/common.py',
                      meson.current_source_dir() / 'scripts/qapi-gen.py'
 ]
 
Signature · 1 line
2.39.2
Reviewed-by on v1 4/17
#9 lore raw

Re: [PATCH 04/17] meson: Fix to make QAPI generator output depend on main.py

Quoted 4 lines · Markus Armbruster

@qapi_gen_depends is missing scripts/qapi/main.py. Fix that, and drop a duplicate scripts/qapi/common.py.

Quoted 11 lines
---
 meson.build | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
meson.build +0 -0
index c44d05a13f..ed24df2ade 100644
@@ -2834,12 +2834,12 @@ qapi_gen_depends = [ meson.current_source_dir() / 'scripts/qapi/__init__.py',
                      meson.current_source_dir() / 'scripts/qapi/expr.py',
                      meson.current_source_dir() / 'scripts/qapi/gen.py',

meson.build qapi_gen_depends = [ meson.current_source_dir() / 'scripts/qapi/__init__.py', · line 2844

Quoted 10 lines
meson.build +1 -1
                      meson.current_source_dir() / 'scripts/qapi/introspect.py',
+                     meson.current_source_dir() / 'scripts/qapi/main.py',
                      meson.current_source_dir() / 'scripts/qapi/parser.py',
                      meson.current_source_dir() / 'scripts/qapi/schema.py',
                      meson.current_source_dir() / 'scripts/qapi/source.py',
                      meson.current_source_dir() / 'scripts/qapi/types.py',
                      meson.current_source_dir() / 'scripts/qapi/visit.py',
-                     meson.current_source_dir() / 'scripts/qapi/common.py',
                      meson.current_source_dir() / 'scripts/qapi-gen.py'
 ]

And here you see why putting things in alphabetical order (when possible) avoids this kind of duplications.

#10 lore raw

Re: [PATCH 04/17] meson: Fix to make QAPI generator output depend on main.py

Quoted 25 lines · Juan Quintela
Quoted 4 lines · Markus Armbruster

@qapi_gen_depends is missing scripts/qapi/main.py. Fix that, and drop a duplicate scripts/qapi/common.py.

Quoted 16 lines
---
 meson.build | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
meson.build +1 -0
index c44d05a13f..ed24df2ade 100644
@@ -2834,12 +2834,12 @@ qapi_gen_depends = [ meson.current_source_dir() / 'scripts/qapi/__init__.py',
                      meson.current_source_dir() / 'scripts/qapi/expr.py',
                      meson.current_source_dir() / 'scripts/qapi/gen.py',
                      meson.current_source_dir() / 'scripts/qapi/introspect.py',
+                     meson.current_source_dir() / 'scripts/qapi/main.py',
                      meson.current_source_dir() / 'scripts/qapi/parser.py',
                      meson.current_source_dir() / 'scripts/qapi/schema.py',
                      meson.current_source_dir() / 'scripts/qapi/source.py',
Quoted 8 lines

meson.build qapi_gen_depends = [ meson.current_source_dir() / 'scripts/qapi/__init__.py', · line 2844

Quoted 5 lines
meson.build +0 -1
                      meson.current_source_dir() / 'scripts/qapi/types.py',
                      meson.current_source_dir() / 'scripts/qapi/visit.py',
-                     meson.current_source_dir() / 'scripts/qapi/common.py',
                      meson.current_source_dir() / 'scripts/qapi-gen.py'
 ]

And here you see why putting things in alphabetical order (when possible) avoids this kind of duplications.

Right.

When Paolo converted this to Meson, he kept the list in alphabetical order, except he added common.py and doc.py again at the end. Probably an editing accident. When Peter later replaced doc.py, he dropped both copies here, but apparently didn't notice the other duplicate.

Thanks!

#11 lore raw

PATCH 5/17 Revert "qapi: BlockExportRemoveMode: move comments to TODO"

In reply to Markus Armbruster

This reverts commit 97cd74f77231f3897838f8db32b659d94803e01f.

The next commit will hide TODO: sections. See there for rationale.

---
 qapi/block-export.json | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)
qapi/block-export.json +5 -5
index 3be3de357f..3ec8ad0ce7 100644
@@ -249,13 +249,13 @@
 #
 # @hard: Drop all connections immediately and remove export.
 #
-# TODO: Potential additional modes to be added in the future:
+# Potential additional modes to be added in the future:
 #
-#       hide: Just hide export from new clients, leave existing connections as is.
-#       Remove export after all clients are disconnected.
+# hide: Just hide export from new clients, leave existing connections as is.
+# Remove export after all clients are disconnected.
 #
-#       soft: Hide export from new clients, answer with ESHUTDOWN for all further
-#       requests from existing clients.
+# soft: Hide export from new clients, answer with ESHUTDOWN for all further
+# requests from existing clients.
 #
 # Since: 2.12
 ##
Signature · 1 line
2.39.2
Reviewed-by on v1 5/17
#12 lore raw

Re: [PATCH 05/17] Revert "qapi: BlockExportRemoveMode: move comments to TODO"

Quoted 3 lines · Markus Armbruster

This reverts commit 97cd74f77231f3897838f8db32b659d94803e01f.

The next commit will hide TODO: sections. See there for rationale.

Reviewing with forward pointers has its own challenges O:-)

Quoted 1 line
#13 lore raw

PATCH 6/17 sphinx/qapidoc: Do not emit TODO sections into user manuals

In reply to Markus Armbruster

QAPI doc comments are for QMP users: they go into the "QEMU QMP Reference Manual" and the "QEMU Storage Daemon QMP Reference Manual".

The doc comment TODO sections are for somebody else, namely for the people who can do: developers. Do not emit them into the user manuals.

This elides the following TODOs:

* SchemaInfoCommand

# TODO: @success-response (currently irrelevant, because it's QGA, not QMP)

This is a note to developers adding introspection to the guest agent. It makes no sense to users.

* @query-hotpluggable-cpus

# TODO: Better documentation; currently there is none.

This is a reminder for developers. It doesn't help users.

* @device_add

# TODO: This command effectively bypasses QAPI completely due to its

  #       "additional arguments" business.  It shouldn't have been added to
  #       the schema in this form.  It should be qapified properly, or
  #       replaced by a properly qapified command.

Likewise.

Eliding them is an improvement.

---
 docs/devel/qapi-code-gen.rst | 5 +++--
 docs/sphinx/qapidoc.py       | 3 +++
 2 files changed, 6 insertions(+), 2 deletions(-)
docs/devel/qapi-code-gen.rst +3 -2
index ff7b74bdb2..6386b58881 100644
@@ -1007,8 +1007,9 @@ A "Since: x.y.z" tagged section lists the release that introduced the
 definition.
 
 An "Example" or "Examples" section is automatically rendered entirely
-as literal fixed-width text.  In other sections, the text is
-formatted, and rST markup can be used.
+as literal fixed-width text.  "TODO" sections are not rendered at all
+(they are for developers, not users of QMP).  In other sections, the
+text is formatted, and rST markup can be used.
 
 For example::
 
docs/sphinx/qapidoc.py +3 -0
index d791b59492..8f3b9997a1 100644
@@ -268,6 +268,9 @@ def _nodes_for_sections(self, doc):
         """Return list of doctree nodes for additional sections"""
         nodelist = []
         for section in doc.sections:
+            if section.name and section.name == 'TODO':
+                # Hide TODO: sections
+                continue
             snode = self._make_section(section.name)
             if section.name and section.name.startswith('Example'):
                 snode += self._nodes_for_example(section.text)
Signature · 1 line
2.39.2
Reviewed-by on v1 6/17
#14 lore raw

Re: [PATCH 06/17] sphinx/qapidoc: Do not emit TODO sections into user manuals

Quoted 30 lines · Markus Armbruster

QAPI doc comments are for QMP users: they go into the "QEMU QMP Reference Manual" and the "QEMU Storage Daemon QMP Reference Manual".

The doc comment TODO sections are for somebody else, namely for the people who can do: developers. Do not emit them into the user manuals.

This elides the following TODOs:

* SchemaInfoCommand

# TODO: @success-response (currently irrelevant, because it's QGA, not
QMP)

This is a note to developers adding introspection to the guest agent. It makes no sense to users.

* @query-hotpluggable-cpus

# TODO: Better documentation; currently there is none.

This is a reminder for developers. It doesn't help users.

* @device_add

# TODO: This command effectively bypasses QAPI completely due to its

  #       "additional arguments" business.  It shouldn't have been added to
  #       the schema in this form.  It should be qapified properly, or
  #       replaced by a properly qapified command.
Quoted 6 lines

Likewise.

Eliding them is an improvement.

Quoted 40 lines
---
 docs/devel/qapi-code-gen.rst | 5 +++--
 docs/sphinx/qapidoc.py       | 3 +++
 2 files changed, 6 insertions(+), 2 deletions(-)
docs/devel/qapi-code-gen.rst +0 -0
index ff7b74bdb2..6386b58881 100644
@@ -1007,8 +1007,9 @@ A "Since: x.y.z" tagged section lists the release

that introduced the
definition.

An "Example" or "Examples" section is automatically rendered entirely

docs/devel/qapi-code-gen.rst +3 -2
-as literal fixed-width text.  In other sections, the text is
-formatted, and rST markup can be used.
+as literal fixed-width text.  "TODO" sections are not rendered at all
+(they are for developers, not users of QMP).  In other sections, the
+text is formatted, and rST markup can be used.
 
 For example::
docs/sphinx/qapidoc.py +3 -1
index d791b59492..8f3b9997a1 100644
@@ -268,6 +268,9 @@ def _nodes_for_sections(self, doc):
         """Return list of doctree nodes for additional sections"""
         nodelist = []
         for section in doc.sections:
+            if section.name and section.name == 'TODO':
+                # Hide TODO: sections
+                continue
             snode = self._make_section(section.name)
             if section.name and section.name.startswith('Example'):
                 snode += self._nodes_for_example(section.text)
--

2.39.2

Reviewed-by on v1 6/17
#15 lore raw

Re: [PATCH 06/17] sphinx/qapidoc: Do not emit TODO sections into user manuals

In reply to Markus Armbruster
Quoted 29 lines · Markus Armbruster

QAPI doc comments are for QMP users: they go into the "QEMU QMP Reference Manual" and the "QEMU Storage Daemon QMP Reference Manual".

The doc comment TODO sections are for somebody else, namely for the people who can do: developers. Do not emit them into the user manuals.

This elides the following TODOs:

* SchemaInfoCommand

# TODO: @success-response (currently irrelevant, because it's QGA, not QMP)

This is a note to developers adding introspection to the guest agent. It makes no sense to users.

* @query-hotpluggable-cpus

# TODO: Better documentation; currently there is none.

This is a reminder for developers. It doesn't help users.

* @device_add

# TODO: This command effectively bypasses QAPI completely due to its

  #       "additional arguments" business.  It shouldn't have been added to
  #       the schema in this form.  It should be qapified properly, or
  #       replaced by a properly qapified command.
Quoted 5 lines

Likewise.

Eliding them is an improvement.

#16 lore raw

PATCH 7/17 qapi: Tidy up a slightly awkward TODO comment

In reply to Markus Armbruster

MigrateSetParameters has a TODO comment sitting right behind its doc comment. I wrote it this way to keep it out of the manual, but that reason is not obvious.

The previous commit (sphinx/qapidoc: Do not emit TODO sections into user manuals) lets me move it into the doc comment as a TODO section.

---
 qapi/migration.json | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)
qapi/migration.json +3 -2
index 82000adce4..11c09800c2 100644
@@ -945,10 +945,11 @@
 # Features:
 # @unstable: Member @x-checkpoint-delay is experimental.
 #
+# TODO: either fuse back into MigrationParameters, or make
+#       MigrationParameters members mandatory
+#
 # Since: 2.4
 ##
-# TODO either fuse back into MigrationParameters, or make
-# MigrationParameters members mandatory
 { 'struct': 'MigrateSetParameters',
   'data': { '*announce-initial': 'size',
             '*announce-max': 'size',
Signature · 1 line
2.39.2
Reviewed-by on v1 7/17
#17 lore raw

Re: [PATCH 07/17] qapi: Tidy up a slightly awkward TODO comment

Quoted 9 lines · Markus Armbruster

MigrateSetParameters has a TODO comment sitting right behind its doc comment. I wrote it this way to keep it out of the manual, but that reason is not obvious.

The previous commit (sphinx/qapidoc: Do not emit TODO sections into user manuals) lets me move it into the doc comment as a TODO section.

Quoted 26 lines
---
 qapi/migration.json | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)
qapi/migration.json +3 -3
index 82000adce4..11c09800c2 100644
@@ -945,10 +945,11 @@
 # Features:
 # @unstable: Member @x-checkpoint-delay is experimental.
 #
+# TODO: either fuse back into MigrationParameters, or make
+#       MigrationParameters members mandatory
+#
 # Since: 2.4
 ##
-# TODO either fuse back into MigrationParameters, or make
-# MigrationParameters members mandatory
 { 'struct': 'MigrateSetParameters',
   'data': { '*announce-initial': 'size',
             '*announce-max': 'size',
--

2.39.2

Reviewed-by on v1 7/17
#18 lore raw

Re: [PATCH 07/17] qapi: Tidy up a slightly awkward TODO comment

In reply to Markus Armbruster
Quoted 8 lines · Markus Armbruster

MigrateSetParameters has a TODO comment sitting right behind its doc comment. I wrote it this way to keep it out of the manual, but that reason is not obvious.

The previous commit (sphinx/qapidoc: Do not emit TODO sections into user manuals) lets me move it into the doc comment as a TODO section.

Quoted 9 lines
---
 qapi/migration.json | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)
qapi/migration.json +0 -0
index 82000adce4..11c09800c2 100644

qapi/migration.json line 951

Quoted 7 lines
qapi/migration.json +3 -0
@@ -945,10 +945,11 @@
 # Features:
 # @unstable: Member @x-checkpoint-delay is experimental.
 #
+# TODO: either fuse back into MigrationParameters, or make
+#       MigrationParameters members mandatory
+#
 # Since: 2.4

2.4 was released in 2015-08-11
There is no hope for something that has been experimental since then.

#19 lore raw

Re: [PATCH 07/17] qapi: Tidy up a slightly awkward TODO comment

Quoted 16 lines · Juan Quintela
Quoted 8 lines · Markus Armbruster

MigrateSetParameters has a TODO comment sitting right behind its doc comment. I wrote it this way to keep it out of the manual, but that reason is not obvious.

The previous commit (sphinx/qapidoc: Do not emit TODO sections into user manuals) lets me move it into the doc comment as a TODO section.

Quoted 4 lines
---
 qapi/migration.json | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)
Quoted 15 lines

qapi/migration.json line 951

Quoted 12 lines
qapi/migration.json +3 -0
index 82000adce4..11c09800c2 100644
@@ -945,10 +945,11 @@
 # Features:
 # @unstable: Member @x-checkpoint-delay is experimental.
 #
+# TODO: either fuse back into MigrationParameters, or make
+#       MigrationParameters members mandatory
+#
 # Since: 2.4

2.4 was released in 2015-08-11
There is no hope for something that has been experimental since then.

I wish it was experimental! It's actually awfully stable technical debt.

Thanks!

#20 lore raw

PATCH 8/17 qapi/dump: Indent bulleted lists consistently

In reply to Markus Armbruster

Documentation of dump-guest-memory contains two bulleted lists. The first one is indented, the second one isn't. Delete the first one's indentation for a more consistent look.

---
 qapi/dump.json | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)
qapi/dump.json +6 -6
index 6fc215dd47..24af1df7db 100644
@@ -44,12 +44,12 @@
 #
 #          Also, paging=true has the following limitations:
 #
-#             1. The guest may be in a catastrophic state or can have corrupted
-#                memory, which cannot be trusted
-#             2. The guest can be in real-mode even if paging is enabled. For
-#                example, the guest uses ACPI to sleep, and ACPI sleep state
-#                goes in real-mode
-#             3. Currently only supported on i386 and x86_64.
+#          1. The guest may be in a catastrophic state or can have corrupted
+#             memory, which cannot be trusted
+#          2. The guest can be in real-mode even if paging is enabled. For
+#             example, the guest uses ACPI to sleep, and ACPI sleep state
+#             goes in real-mode
+#          3. Currently only supported on i386 and x86_64.
 #
 # @protocol: the filename or file descriptor of the vmcore. The supported
 #            protocols are:
Signature · 1 line
2.39.2
#22 lore raw

PATCH 9/17 tests/qapi-schema/doc-good: Improve a comment

In reply to Markus Armbruster

The QAPI generator doesn't reject undocumented members and features (yet). doc-good.json covers this, with clear "is undocumented" notes to signal intent.

Except for @Variant1 member @var1, where it's "(but no @var: line)". Less clear. Replace by "@var1 is undocumented".

---
 tests/qapi-schema/doc-good.json | 4 +++-
 tests/qapi-schema/doc-good.out  | 2 ++
 2 files changed, 5 insertions(+), 1 deletion(-)
tests/qapi-schema/doc-good.json +3 -1
index 74745fb405..445471daee 100644
@@ -83,7 +83,9 @@
 #
 # A paragraph
 #
-# Another paragraph (but no @var: line)
+# Another paragraph
+#
+# @var1 is undocumented
 #
 # Features:
 # @variant1-feat: a feature
tests/qapi-schema/doc-good.out +2 -0
index 9dd65b9d92..afa48dcd94 100644
@@ -123,6 +123,8 @@ doc symbol=Variant1
 A paragraph
 
 Another paragraph (but no @var: line)
+
+@var1 is undocumented
     arg=var1
 
     feature=variant1-feat
Signature · 1 line
2.39.2
Reviewed-by on v1 9/17
#23 lore raw

Re: [PATCH 09/17] tests/qapi-schema/doc-good: Improve a comment

Quoted 8 lines · Markus Armbruster

The QAPI generator doesn't reject undocumented members and features (yet). doc-good.json covers this, with clear "is undocumented" notes to signal intent.

Except for @Variant1 member @var1, where it's "(but no @var: line)". Less clear. Replace by "@var1 is undocumented".

#24 lore raw

PATCH 10/17 tests/qapi-schema/doc-good: Improve argument description tests

In reply to Markus Armbruster

Improve the comments to better describe what they test.

Cover argument description starting on a new line indented. This style isn't documented in docs/devel/qapi-code-gen.rst. qapi-gen.py accepts it, but messes up indentation: it's stripped from the first line, not subsequent ones. The next commit will fix this.

---
 tests/qapi-schema/doc-good.json | 15 +++++++++------
 tests/qapi-schema/doc-good.out  | 16 +++++++++-------
 2 files changed, 18 insertions(+), 13 deletions(-)
tests/qapi-schema/doc-good.json +9 -6
index 445471daee..34c3dcbe97 100644
@@ -54,7 +54,7 @@
 ##
 # @Enum:
 #
-# @one: The _one_ {and only}
+# @one: The _one_ {and only}, description on the same line
 #
 # Features:
 # @enum-feat: Also _one_ {and only}
@@ -73,7 +73,8 @@
 # @Base:
 #
 # @base1:
-# the first member
+# description starts on a new line,
+# not indented
 ##
 { 'struct': 'Base', 'data': { 'base1': 'Enum' },
   'if': { 'all': ['IFALL1', 'IFALL2'] } }
@@ -120,7 +121,8 @@
 ##
 # @Alternate:
 #
-# @i: an integer
+# @i: description starts on the same line
+#     remainder indented the same
 #     @b is undocumented
 #
 # Features:
@@ -138,10 +140,11 @@
 ##
 # @cmd:
 #
-# @arg1: the first argument
+# @arg1:
+#     description starts on a new line,
+#     indented
 #
-# @arg2: the second
-#        argument
+# @arg2: the second argument
 #
 # Features:
 # @cmd-feat1: a feature
tests/qapi-schema/doc-good.out +9 -7
index afa48dcd94..2ba72ae558 100644
@@ -104,7 +104,7 @@ doc symbol=Enum
     body=
 
     arg=one
-The _one_ {and only}
+The _one_ {and only}, description on the same line
     arg=two
 
     feature=enum-feat
@@ -117,12 +117,13 @@ doc symbol=Base
     body=
 
     arg=base1
-the first member
+description starts on a new line,
+not indented
 doc symbol=Variant1
     body=
 A paragraph
 
-Another paragraph (but no @var: line)
+Another paragraph
 
 @var1 is undocumented
     arg=var1
@@ -143,7 +144,8 @@ doc symbol=Alternate
     body=
 
     arg=i
-an integer
+description starts on the same line
+remainder indented the same
 @b is undocumented
     arg=b
 
@@ -156,10 +158,10 @@ doc symbol=cmd
     body=
 
     arg=arg1
-the first argument
+description starts on a new line,
+    indented
     arg=arg2
-the second
-argument
+the second argument
     arg=arg3
 
     feature=cmd-feat1
Signature · 1 line
2.39.2
Reviewed-by on v1 10/17
#25 lore raw

Re: [PATCH 10/17] tests/qapi-schema/doc-good: Improve argument description tests

Quoted 8 lines · Markus Armbruster

Improve the comments to better describe what they test.

Cover argument description starting on a new line indented. This style isn't documented in docs/devel/qapi-code-gen.rst. qapi-gen.py accepts it, but messes up indentation: it's stripped from the first line, not subsequent ones. The next commit will fix this.

tests/qapi-schema/doc-good.json line 128

Quoted 9 lines

##
# @Alternate:
#

tests/qapi-schema/doc-good.json +2 -1
-# @i: an integer
+# @i: description starts on the same line
+#     remainder indented the same
 #     @b is undocumented
 #
 # Features:

Just curious, what is trying to convey this
@b is undocumented
At the same indentation that the description of @i?

#26 lore raw

Re: [PATCH 10/17] tests/qapi-schema/doc-good: Improve argument description tests

Quoted 12 lines · Juan Quintela
Quoted 8 lines · Markus Armbruster

Improve the comments to better describe what they test.

Cover argument description starting on a new line indented. This style isn't documented in docs/devel/qapi-code-gen.rst. qapi-gen.py accepts it, but messes up indentation: it's stripped from the first line, not subsequent ones. The next commit will fix this.

Quoted 13 lines

tests/qapi-schema/doc-good.json line 128

Quoted 9 lines

##
# @Alternate:
#

tests/qapi-schema/doc-good.json +2 -1
-# @i: an integer
+# @i: description starts on the same line
+#     remainder indented the same
 #     @b is undocumented
 #
 # Features:

Just curious, what is trying to convey this
@b is undocumented
At the same indentation that the description of @i?

Writing it like

# @i: description starts on the same line
# remainder indented the same
# @b is undocumented
#
# Features:
# @alt-feat: a feature

fails with "unexpected de-indent (expected at least 4 spaces)". That's because the @b line is part of the argument section @i, and the doc parser insists its indented consistently. Guards against some editing accidents, like forgetting the ':'.

Writing it like

# @i: description starts on the same line
# remainder indented the same
#
# @b is undocumented
#
# Features:
# @alt-feat: a feature

fails with "'@alt-feat:' can't follow 'None' section". That's because the @b line is now a section of its own, and the doc parser requires sections to be in a certain order. Similar guard against editing accidents. Not foolproof; it only works here because a feature section follows. If we wanted sane syntax, we would've stuck to TexInfo.

The error message is bad; I'll improve it.

Thanks!

#27 lore raw

Re: [PATCH 10/17] tests/qapi-schema/doc-good: Improve argument description tests

Quoted 52 lines · Markus Armbruster
Quoted 12 lines · Juan Quintela
Quoted 8 lines · Markus Armbruster

Improve the comments to better describe what they test.

Cover argument description starting on a new line indented. This style isn't documented in docs/devel/qapi-code-gen.rst. qapi-gen.py accepts it, but messes up indentation: it's stripped from the first line, not subsequent ones. The next commit will fix this.

Quoted 13 lines

tests/qapi-schema/doc-good.json line 128

Quoted 9 lines

##
# @Alternate:
#

tests/qapi-schema/doc-good.json +2 -1
-# @i: an integer
+# @i: description starts on the same line
+#     remainder indented the same
 #     @b is undocumented
 #
 # Features:

Just curious, what is trying to convey this
@b is undocumented
At the same indentation that the description of @i?

Writing it like

# @i: description starts on the same line
# remainder indented the same
# @b is undocumented
#
# Features:
# @alt-feat: a feature

fails with "unexpected de-indent (expected at least 4 spaces)". That's because the @b line is part of the argument section @i, and the doc parser insists its indented consistently. Guards against some editing accidents, like forgetting the ':'.

Writing it like

# @i: description starts on the same line
# remainder indented the same
#
# @b is undocumented
#
# Features:
# @alt-feat: a feature

Quoted 7 lines

fails with "'@alt-feat:' can't follow 'None' section". That's because the @b line is now a section of its own, and the doc parser requires sections to be in a certain order. Similar guard against editing accidents. Not foolproof; it only works here because a feature section follows. If we wanted sane syntax, we would've stuck to TexInfo.

The error message is bad; I'll improve it.

Thanks for the explanation.

#28 lore raw

PATCH 11/17 qapi: Fix argument description indentation stripping

In reply to Markus Armbruster

When an argument's description starts on the line after the "#arg: " line, indentation is stripped only from the description's first line, as demonstrated by the previous commit. Moreover, subsequent lines with less indentation are not rejected.

Make the first line's indentation the expected indentation for the remainder of the description. This fixes indentation stripping, and also requires at least that much indentation.

---
 scripts/qapi/parser.py         | 20 +++++++++++---------
 tests/qapi-schema/doc-good.out |  2 +-
 2 files changed, 12 insertions(+), 10 deletions(-)
scripts/qapi/parser.py +11 -9
index 7b49d3ab05..ddc14ceaba 100644
@@ -483,7 +483,9 @@ def append(self, line: str) -> None:
             # Blank lines are always OK.
             if line:
                 indent = must_match(r'\s*', line).end()
-                if indent < self._indent:
+                if self._indent < 0:
+                    self._indent = indent
+                elif indent < self._indent:
                     raise QAPIParseError(
                         self._parser,
                         "unexpected de-indent (expected at least %d spaces)" %
@@ -631,9 +633,9 @@ def _append_args_line(self, line: str) -> None:
             indent = must_match(r'@\S*:\s*', line).end()
             line = line[indent:]
             if not line:
-                # Line was just the "@arg:" header; following lines
-                # are not indented
-                indent = 0
+                # Line was just the "@arg:" header
+                # The next non-blank line determines expected indent
+                indent = -1
             else:
                 line = ' ' * indent + line
             self._start_args_section(name[1:-1], indent)
@@ -666,9 +668,9 @@ def _append_features_line(self, line: str) -> None:
             indent = must_match(r'@\S*:\s*', line).end()
             line = line[indent:]
             if not line:
-                # Line was just the "@arg:" header; following lines
-                # are not indented
-                indent = 0
+                # Line was just the "@arg:" header
+                # The next non-blank line determines expected indent
+                indent = -1
             else:
                 line = ' ' * indent + line
             self._start_features_section(name[1:-1], indent)
@@ -712,8 +714,8 @@ def _append_various_line(self, line: str) -> None:
             indent = must_match(r'\S*:\s*', line).end()
             line = line[indent:]
             if not line:
-                # Line was just the "Section:" header; following lines
-                # are not indented
+                # Line was just the "Section:" header
+                # The next non-blank line determines expected indent
                 indent = 0
             else:
                 line = ' ' * indent + line
tests/qapi-schema/doc-good.out +1 -1
index 2ba72ae558..277371acc8 100644
@@ -159,7 +159,7 @@ doc symbol=cmd
 
     arg=arg1
 description starts on a new line,
-    indented
+indented
     arg=arg2
 the second argument
     arg=arg3
Signature · 1 line
2.39.2
Reviewed-by on v1 11/17
#29 lore raw

Re: [PATCH 11/17] qapi: Fix argument description indentation stripping

Quoted 10 lines · Markus Armbruster

When an argument's description starts on the line after the "#arg: " line, indentation is stripped only from the description's first line, as demonstrated by the previous commit. Moreover, subsequent lines with less indentation are not rejected.

Make the first line's indentation the expected indentation for the remainder of the description. This fixes indentation stripping, and also requires at least that much indentation.

#30 lore raw

PATCH 12/17 qapi: Rewrite parsing of doc comment section symbols and tags

In reply to Markus Armbruster

To recognize a line starting with a section symbol and or tag, we first split it at the first space, then examine the part left of the space. We can just as well examine the unsplit line, so do that.

---
 scripts/qapi/parser.py | 51 +++++++++++++++++++-----------------------
 1 file changed, 23 insertions(+), 28 deletions(-)
scripts/qapi/parser.py +23 -28
index ddc14ceaba..fc04c4573e 100644
@@ -560,12 +560,12 @@ def end_comment(self) -> None:
         self._switch_section(QAPIDoc.NullSection(self._parser))
 
     @staticmethod
-    def _is_section_tag(name: str) -> bool:
-        return name in ('Returns:', 'Since:',
-                        # those are often singular or plural
-                        'Note:', 'Notes:',
-                        'Example:', 'Examples:',
-                        'TODO:')
+    def _match_at_name_colon(string: str) -> re.Match:
+        return re.match(r'@([^:]*): *', string)
+
+    @staticmethod
+    def _match_section_tag(string: str) -> re.Match:
+        return re.match(r'(Returns|Since|Notes?|Examples?|TODO): *', string)
 
     def _append_body_line(self, line: str) -> None:
         """
@@ -581,7 +581,6 @@ def _append_body_line(self, line: str) -> None:
 
         Else, append the line to the current section.
         """
-        name = line.split(' ', 1)[0]
         # FIXME not nice: things like '#  @foo:' and '# @foo: ' aren't
         # recognized, and get silently treated as ordinary text
         if not self.symbol and not self.body.text and line.startswith('@'):
@@ -595,12 +594,12 @@ def _append_body_line(self, line: str) -> None:
                     self._parser, "name required after '@'")
         elif self.symbol:
             # This is a definition documentation block
-            if name.startswith('@') and name.endswith(':'):
+            if self._match_at_name_colon(line):
                 self._append_line = self._append_args_line
                 self._append_args_line(line)
             elif line == 'Features:':
                 self._append_line = self._append_features_line
-            elif self._is_section_tag(name):
+            elif self._match_section_tag(line):
                 self._append_line = self._append_various_line
                 self._append_various_line(line)
             else:
@@ -621,16 +620,15 @@ def _append_args_line(self, line: str) -> None:
         Else, append the line to the current section.
 
         """
-        name = line.split(' ', 1)[0]
-
-        if name.startswith('@') and name.endswith(':'):
+        if match := self._match_at_name_colon(line):
             # If line is "@arg:   first line of description", find
             # the index of 'f', which is the indent we expect for any
             # following lines.  We then remove the leading "@arg:"
             # from line and replace it with spaces so that 'f' has the
             # same index as it did in the original line and can be
             # handled the same way we will handle following lines.
-            indent = must_match(r'@\S*:\s*', line).end()
+            name = match.group(1)
+            indent = match.end()
             line = line[indent:]
             if not line:
                 # Line was just the "@arg:" header
@@ -638,8 +636,8 @@ def _append_args_line(self, line: str) -> None:
                 indent = -1
             else:
                 line = ' ' * indent + line
-            self._start_args_section(name[1:-1], indent)
-        elif self._is_section_tag(name):
+            self._start_args_section(name, indent)
+        elif self._match_section_tag(line):
             self._append_line = self._append_various_line
             self._append_various_line(line)
             return
@@ -656,16 +654,15 @@ def _append_args_line(self, line: str) -> None:
         self._append_freeform(line)
 
     def _append_features_line(self, line: str) -> None:
-        name = line.split(' ', 1)[0]
-
-        if name.startswith('@') and name.endswith(':'):
+        if match := self._match_at_name_colon(line):
             # If line is "@arg:   first line of description", find
             # the index of 'f', which is the indent we expect for any
             # following lines.  We then remove the leading "@arg:"
             # from line and replace it with spaces so that 'f' has the
             # same index as it did in the original line and can be
             # handled the same way we will handle following lines.
-            indent = must_match(r'@\S*:\s*', line).end()
+            name = match.group(1)
+            indent = match.end()
             line = line[indent:]
             if not line:
                 # Line was just the "@arg:" header
@@ -673,8 +670,8 @@ def _append_features_line(self, line: str) -> None:
                 indent = -1
             else:
                 line = ' ' * indent + line
-            self._start_features_section(name[1:-1], indent)
-        elif self._is_section_tag(name):
+            self._start_features_section(name, indent)
+        elif self._match_section_tag(line):
             self._append_line = self._append_various_line
             self._append_various_line(line)
             return
@@ -698,13 +695,11 @@ def _append_various_line(self, line: str) -> None:
 
         Else, append the line to the current section.
         """
-        name = line.split(' ', 1)[0]
-
-        if name.startswith('@') and name.endswith(':'):
+        if match := self._match_at_name_colon(line):
             raise QAPIParseError(self._parser,
-                                 "'%s' can't follow '%s' section"
-                                 % (name, self.sections[0].name))
-        if self._is_section_tag(name):
+                                 "'@%s:' can't follow '%s' section"
+                                 % (match.group(1), self.sections[0].name))
+        if match := self._match_section_tag(line):
             # If line is "Section:   first line of description", find
             # the index of 'f', which is the indent we expect for any
             # following lines.  We then remove the leading "Section:"
@@ -719,7 +714,7 @@ def _append_various_line(self, line: str) -> None:
                 indent = 0
             else:
                 line = ' ' * indent + line
-            self._start_section(name[:-1], indent)
+            self._start_section(match.group(1), indent)
 
         self._append_freeform(line)
 
Signature · 1 line
2.39.2
Reviewed-by on v1 12/17
#31 lore raw

Re: [PATCH 12/17] qapi: Rewrite parsing of doc comment section symbols and tags

Quoted 5 lines · Markus Armbruster

To recognize a line starting with a section symbol and or tag, we first split it at the first space, then examine the part left of the space. We can just as well examine the unsplit line, so do that.

My python regexp kungfu is at the limit with this patch, so take it as you wish. I understand the intent (very good commit message) and "more or less" how it is done. Important words on the previous sentence are "more or less". O:-)

#32 lore raw

Re: [PATCH 12/17] qapi: Rewrite parsing of doc comment section symbols and tags

Quoted 5 lines · Juan Quintela
Quoted 4 lines · Markus Armbruster

To recognize a line starting with a section symbol and or tag, we first split it at the first space, then examine the part left of the space. We can just as well examine the unsplit line, so do that.

Quoted 8 lines
Quoted 1 line

My python regexp kungfu is at the limit with this patch, so take it as you wish. I understand the intent (very good commit message) and "more or less" how it is done. Important words on the previous sentence are "more or less". O:-)

Tests pass, so what could possibly go wrong (famous last words).

Thanks!

#33 lore raw

Re: [PATCH 12/17] qapi: Rewrite parsing of doc comment section symbols and tags

In reply to Markus Armbruster
Quoted 136 lines · Markus Armbruster

To recognize a line starting with a section symbol and or tag, we first split it at the first space, then examine the part left of the space. We can just as well examine the unsplit line, so do that.

---
 scripts/qapi/parser.py | 51 +++++++++++++++++++-----------------------
 1 file changed, 23 insertions(+), 28 deletions(-)
scripts/qapi/parser.py +22 -27
index ddc14ceaba..fc04c4573e 100644
@@ -560,12 +560,12 @@ def end_comment(self) -> None:
         self._switch_section(QAPIDoc.NullSection(self._parser))
 
     @staticmethod
-    def _is_section_tag(name: str) -> bool:
-        return name in ('Returns:', 'Since:',
-                        # those are often singular or plural
-                        'Note:', 'Notes:',
-                        'Example:', 'Examples:',
-                        'TODO:')
+    def _match_at_name_colon(string: str) -> re.Match:
+        return re.match(r'@([^:]*): *', string)
+
+    @staticmethod
+    def _match_section_tag(string: str) -> re.Match:
+        return re.match(r'(Returns|Since|Notes?|Examples?|TODO): *', string)
 
     def _append_body_line(self, line: str) -> None:
         """
@@ -581,7 +581,6 @@ def _append_body_line(self, line: str) -> None:
 
         Else, append the line to the current section.
         """
-        name = line.split(' ', 1)[0]
         # FIXME not nice: things like '#  @foo:' and '# @foo: ' aren't
         # recognized, and get silently treated as ordinary text
         if not self.symbol and not self.body.text and line.startswith('@'):
@@ -595,12 +594,12 @@ def _append_body_line(self, line: str) -> None:
                     self._parser, "name required after '@'")
         elif self.symbol:
             # This is a definition documentation block
-            if name.startswith('@') and name.endswith(':'):
+            if self._match_at_name_colon(line):
                 self._append_line = self._append_args_line
                 self._append_args_line(line)
             elif line == 'Features:':
                 self._append_line = self._append_features_line
-            elif self._is_section_tag(name):
+            elif self._match_section_tag(line):
                 self._append_line = self._append_various_line
                 self._append_various_line(line)
             else:
@@ -621,16 +620,15 @@ def _append_args_line(self, line: str) -> None:
         Else, append the line to the current section.
 
         """
-        name = line.split(' ', 1)[0]
-
-        if name.startswith('@') and name.endswith(':'):
+        if match := self._match_at_name_colon(line):
             # If line is "@arg:   first line of description", find
             # the index of 'f', which is the indent we expect for any
             # following lines.  We then remove the leading "@arg:"
             # from line and replace it with spaces so that 'f' has the
             # same index as it did in the original line and can be
             # handled the same way we will handle following lines.
-            indent = must_match(r'@\S*:\s*', line).end()
+            name = match.group(1)
+            indent = match.end()
             line = line[indent:]
             if not line:
                 # Line was just the "@arg:" header
@@ -638,8 +636,8 @@ def _append_args_line(self, line: str) -> None:
                 indent = -1
             else:
                 line = ' ' * indent + line
-            self._start_args_section(name[1:-1], indent)
-        elif self._is_section_tag(name):
+            self._start_args_section(name, indent)
+        elif self._match_section_tag(line):
             self._append_line = self._append_various_line
             self._append_various_line(line)
             return
@@ -656,16 +654,15 @@ def _append_args_line(self, line: str) -> None:
         self._append_freeform(line)
 
     def _append_features_line(self, line: str) -> None:
-        name = line.split(' ', 1)[0]
-
-        if name.startswith('@') and name.endswith(':'):
+        if match := self._match_at_name_colon(line):
             # If line is "@arg:   first line of description", find
             # the index of 'f', which is the indent we expect for any
             # following lines.  We then remove the leading "@arg:"
             # from line and replace it with spaces so that 'f' has the
             # same index as it did in the original line and can be
             # handled the same way we will handle following lines.
-            indent = must_match(r'@\S*:\s*', line).end()
+            name = match.group(1)
+            indent = match.end()
             line = line[indent:]
             if not line:
                 # Line was just the "@arg:" header
@@ -673,8 +670,8 @@ def _append_features_line(self, line: str) -> None:
                 indent = -1
             else:
                 line = ' ' * indent + line
-            self._start_features_section(name[1:-1], indent)
-        elif self._is_section_tag(name):
+            self._start_features_section(name, indent)
+        elif self._match_section_tag(line):
             self._append_line = self._append_various_line
             self._append_various_line(line)
             return
@@ -698,13 +695,11 @@ def _append_various_line(self, line: str) -> None:
 
         Else, append the line to the current section.
         """
-        name = line.split(' ', 1)[0]
-
-        if name.startswith('@') and name.endswith(':'):
+        if match := self._match_at_name_colon(line):
             raise QAPIParseError(self._parser,
-                                 "'%s' can't follow '%s' section"
-                                 % (name, self.sections[0].name))
-        if self._is_section_tag(name):
+                                 "'@%s:' can't follow '%s' section"
+                                 % (match.group(1), self.sections[0].name))
+        if match := self._match_section_tag(line):
             # If line is "Section:   first line of description", find
             # the index of 'f', which is the indent we expect for any
             # following lines.  We then remove the leading "Section:"

scripts/qapi/parser.py def _append_various_line(self, line: str) -> None: · line 719

Quoted 7 lines
scripts/qapi/parser.py +1 -1
@@ -719,7 +714,7 @@ def _append_various_line(self, line: str) -> None:
                 indent = 0
             else:
                 line = ' ' * indent + line
-            self._start_section(name[:-1], indent)
+            self._start_section(match.group(1), indent)
 
         self._append_freeform(line)

Need to squash in the appended patch for Python 3.7 and older.

My job description doesn't include "collect paper cuts", but it totally should.

scripts/qapi/parser.py +8 -4
index 22ee631198..4923a59d60 100644
@@ -623,7 +623,8 @@ def _append_args_line(self, line: str) -> None:
         Else, append the line to the current section.
 
         """
-        if match := self._match_at_name_colon(line):
+        match = self._match_at_name_colon(line)
+        if match:
             line = line[match.end():]
             self._start_args_section(match.group(1))
         elif self._match_section_tag(line):
@@ -643,7 +644,8 @@ def _append_args_line(self, line: str) -> None:
         self._append_freeform(line)
 
     def _append_features_line(self, line: str) -> None:
-        if match := self._match_at_name_colon(line):
+        match = self._match_at_name_colon(line)
+        if match:
             line = line[match.end():]
             self._start_features_section(match.group(1))
         elif self._match_section_tag(line):
@@ -670,11 +672,13 @@ def _append_various_line(self, line: str) -> None:
 
         Else, append the line to the current section.
         """
-        if match := self._match_at_name_colon(line):
+        match = self._match_at_name_colon(line)
+        if match:
             raise QAPIParseError(self._parser,
                                  "'@%s:' can't follow '%s' section"
                                  % (match.group(1), self.sections[0].name))
-        if match := self._match_section_tag(line):
+        match = self._match_section_tag(line)
+        if match:
             line = line[match.end():]
             self._start_section(match.group(1))
 
#34 lore raw

PATCH 13/17 qapi: Relax doc string @name: description indentation rules

In reply to Markus Armbruster

The QAPI schema doc comment language provides special syntax for command and event arguments, struct and union members, alternate branches, enumeration values, and features: descriptions starting with "@name:".

By convention, we format them like this:

# @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit,
# sed do eiusmod tempor incididunt ut labore et dolore
# magna aliqua.

Okay for names as short as "name", but we have much longer ones. Their description gets squeezed against the right margin, like this:

# @dirty-sync-missed-zero-copy: Number of times dirty RAM synchronization could
# not avoid copying dirty pages. This is between
# 0 and @dirty-sync-count * @multifd-channels.
# (since 7.1)

The description text is effectively just 50 characters wide. Easy enough to read, but can be cumbersome to write.

The awkward squeeze against the right margin makes people go beyond it, which produces two undesirables: arguments about style, and descriptions that are unnecessarily hard to read, like this one:

# @postcopy-vcpu-blocktime: list of the postcopy blocktime per vCPU. This is
# only present when the postcopy-blocktime migration capability
# is enabled. (Since 3.0)

We could instead format it like

# @postcopy-vcpu-blocktime:
# list of the postcopy blocktime per vCPU. This is only present # when the postcopy-blocktime migration capability is # enabled. (Since 3.0)

or, since the commit before previous, like

# @postcopy-vcpu-blocktime:
# list of the postcopy blocktime per vCPU. This is only present
# when the postcopy-blocktime migration capability is
# enabled. (Since 3.0)

However, I'd rather have

# @postcopy-vcpu-blocktime: list of the postcopy blocktime per vCPU.
# This is only present when the postcopy-blocktime migration
# capability is enabled. (Since 3.0)

because this is how rST field and option lists work.

To get this, we need to let the first non-blank line after the "@name:" line determine expected indentation.

This fills up the indentation pitfall mentioned in docs/devel/qapi-code-gen.rst. A related pitfall still exists. Update the text to show it.

---
 docs/devel/qapi-code-gen.rst          | 10 ++--
 scripts/qapi/parser.py                | 73 +++++++--------------------
 tests/qapi-schema/doc-bad-indent.err  |  2 +-
 tests/qapi-schema/doc-bad-indent.json |  3 +-
 tests/qapi-schema/doc-good.json       |  3 +-
 tests/qapi-schema/doc-good.out        |  3 +-
 6 files changed, 32 insertions(+), 62 deletions(-)
docs/devel/qapi-code-gen.rst +7 -3
index 6386b58881..875f893be2 100644
@@ -1074,10 +1074,14 @@ Indentation matters.  Bad example::
 
  # @none: None (no memory side cache in this proximity domain,
  #              or cache associativity unknown)
+ #     (since 5.0)
 
-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)".
+The last line's de-indent is wrong.  The second and subsequent lines
+need to line up with each other, like this::
+
+ # @none: None (no memory side cache in this proximity domain,
+ #     or cache associativity unknown)
+ #     (since 5.0)
 
 Section tags are case-sensitive and end with a colon.  Good example::
 
scripts/qapi/parser.py +18 -55

114 lines not on this page · raw message

tests/qapi-schema/doc-bad-indent.err +1 -1
index 67844539bd..3c9699a8e0 100644
@@ -1 +1 @@
-doc-bad-indent.json:6:1: unexpected de-indent (expected at least 4 spaces)
+doc-bad-indent.json:7:1: unexpected de-indent (expected at least 2 spaces)
tests/qapi-schema/doc-bad-indent.json +2 -1
index edde8f21dc..3f22a27717 100644
@@ -3,6 +3,7 @@
 ##
 # @foo:
 # @a: line one
-# line two is wrongly indented
+#   line two
+# line three is wrongly indented
 ##
 { 'command': 'foo', 'data': { 'a': 'int' } }
tests/qapi-schema/doc-good.json +2 -1
index 34c3dcbe97..354dfdf461 100644
@@ -144,7 +144,8 @@
 #     description starts on a new line,
 #     indented
 #
-# @arg2: the second argument
+# @arg2: description starts on the same line
+#     remainder indented differently
 #
 # Features:
 # @cmd-feat1: a feature
tests/qapi-schema/doc-good.out +2 -1
index 277371acc8..24d9ea954d 100644
@@ -161,7 +161,8 @@ doc symbol=cmd
 description starts on a new line,
 indented
     arg=arg2
-the second argument
+description starts on the same line
+remainder indented differently
     arg=arg3
 
     feature=cmd-feat1
Signature · 1 line
2.39.2
Reviewed-by on v1 13/17
#35 lore raw

Re: [PATCH 13/17] qapi: Relax doc string @name: description indentation rules

Quoted 52 lines · Markus Armbruster

The QAPI schema doc comment language provides special syntax for command and event arguments, struct and union members, alternate branches, enumeration values, and features: descriptions starting with "@name:".

By convention, we format them like this:

# @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit,
# sed do eiusmod tempor incididunt ut labore et dolore
# magna aliqua.

Okay for names as short as "name", but we have much longer ones. Their description gets squeezed against the right margin, like this:

# @dirty-sync-missed-zero-copy: Number of times dirty RAM synchronization could
# not avoid copying dirty pages. This is between
# 0 and @dirty-sync-count * @multifd-channels.
# (since 7.1)

The description text is effectively just 50 characters wide. Easy enough to read, but can be cumbersome to write.

The awkward squeeze against the right margin makes people go beyond it, which produces two undesirables: arguments about style, and descriptions that are unnecessarily hard to read, like this one:

# @postcopy-vcpu-blocktime: list of the postcopy blocktime per vCPU. This is
# only present when the postcopy-blocktime migration capability
# is enabled. (Since 3.0)

We could instead format it like

# @postcopy-vcpu-blocktime:
# list of the postcopy blocktime per vCPU. This is only present # when the postcopy-blocktime migration capability is # enabled. (Since 3.0)

or, since the commit before previous, like

# @postcopy-vcpu-blocktime:
# list of the postcopy blocktime per vCPU. This is only present
# when the postcopy-blocktime migration capability is
# enabled. (Since 3.0)

However, I'd rather have

# @postcopy-vcpu-blocktime: list of the postcopy blocktime per vCPU.
# This is only present when the postcopy-blocktime migration
# capability is enabled. (Since 3.0)

because this is how rST field and option lists work.

Quoted 8 lines

To get this, we need to let the first non-blank line after the "@name:" line determine expected indentation.

This fills up the indentation pitfall mentioned in docs/devel/qapi-code-gen.rst. A related pitfall still exists. Update the text to show it.

Quoted 5 lines
---
 docs/devel/qapi-code-gen.rst          | 10 ++--
 scripts/qapi/parser.py                | 73 +++++++--------------------
 tests/qapi-schema/doc-bad-indent.err  |  2 +-
 tests/qapi-schema/doc-bad-indent.json |  3 +-

bad order of files

Quoted 2 lines
 tests/qapi-schema/doc-good.json       |  3 +-
 tests/qapi-schema/doc-good.out        |  3 +-

good order of files

Should we tweak orderfiles so it displays first the json, and the err or out files. reviewing json and then output makes things (at least to me) simpler.

#36 lore raw

Re: [PATCH 13/17] qapi: Relax doc string @name: description indentation rules

Quoted 72 lines · Juan Quintela
Quoted 52 lines · Markus Armbruster

The QAPI schema doc comment language provides special syntax for command and event arguments, struct and union members, alternate branches, enumeration values, and features: descriptions starting with "@name:".

By convention, we format them like this:

# @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit,
# sed do eiusmod tempor incididunt ut labore et dolore
# magna aliqua.

Okay for names as short as "name", but we have much longer ones. Their description gets squeezed against the right margin, like this:

# @dirty-sync-missed-zero-copy: Number of times dirty RAM synchronization could
# not avoid copying dirty pages. This is between
# 0 and @dirty-sync-count * @multifd-channels.
# (since 7.1)

The description text is effectively just 50 characters wide. Easy enough to read, but can be cumbersome to write.

The awkward squeeze against the right margin makes people go beyond it, which produces two undesirables: arguments about style, and descriptions that are unnecessarily hard to read, like this one:

# @postcopy-vcpu-blocktime: list of the postcopy blocktime per vCPU. This is
# only present when the postcopy-blocktime migration capability
# is enabled. (Since 3.0)

We could instead format it like

# @postcopy-vcpu-blocktime:
# list of the postcopy blocktime per vCPU. This is only present # when the postcopy-blocktime migration capability is # enabled. (Since 3.0)

or, since the commit before previous, like

# @postcopy-vcpu-blocktime:
# list of the postcopy blocktime per vCPU. This is only present
# when the postcopy-blocktime migration capability is
# enabled. (Since 3.0)

However, I'd rather have

# @postcopy-vcpu-blocktime: list of the postcopy blocktime per vCPU.
# This is only present when the postcopy-blocktime migration
# capability is enabled. (Since 3.0)

because this is how rST field and option lists work.

Quoted 8 lines

To get this, we need to let the first non-blank line after the "@name:" line determine expected indentation.

This fills up the indentation pitfall mentioned in docs/devel/qapi-code-gen.rst. A related pitfall still exists. Update the text to show it.

Quoted 5 lines
---
 docs/devel/qapi-code-gen.rst          | 10 ++--
 scripts/qapi/parser.py                | 73 +++++++--------------------
 tests/qapi-schema/doc-bad-indent.err  |  2 +-
 tests/qapi-schema/doc-bad-indent.json |  3 +-

bad order of files

Quoted 8 lines
Quoted 2 lines
 tests/qapi-schema/doc-good.json       |  3 +-
 tests/qapi-schema/doc-good.out        |  3 +-

good order of files

Should we tweak orderfiles so it displays first the json, and the err or out files. reviewing json and then output makes things (at least to me) simpler.

I'll look into it.

Thanks!

author Reviewed-by Philippe Mathieu-Daudé
#37 lore raw

Re: [PATCH 13/17] qapi: Relax doc string @name: description indentation rules

Quoted 1 line · Markus Armbruster

Juan Quintela <[email protected]> writes:

[...]

Quoted 12 lines
Quoted 12 lines
Quoted 4 lines
 docs/devel/qapi-code-gen.rst          | 10 ++--
 scripts/qapi/parser.py                | 73 +++++++--------------------
 tests/qapi-schema/doc-bad-indent.err  |  2 +-
 tests/qapi-schema/doc-bad-indent.json |  3 +-

bad order of files

Quoted 2 lines
 tests/qapi-schema/doc-good.json       |  3 +-
 tests/qapi-schema/doc-good.out        |  3 +-

good order of files

Quoted 7 lines
Quoted 3 lines

Should we tweak orderfiles so it displays first the json, and the err or out files. reviewing json and then output makes things (at least to me) simpler.

I'll look into it.

Thanks!

We used to put the tests/qapi-schema/*json first, and it was annoying enough for me to change it in commit b1862ee6233. Any other ideas?

commit b1862ee6233805172bab89a1fc44e929dcdbd9fa

Author: Markus Armbruster <[email protected]>
Date:   Fri Sep 13 22:13:34 2019 +0200

scripts/git.orderfile: Match QAPI schema more precisely

Pattern *.json also matches the tests/qapi-schema/*.json. Separates them from the tests/qapi-schema/*.{err,exit,out} in diffs. I hate that. Change the pattern to match just the "real" QAPI schemata.

Message-Id: <[email protected]>

scripts/git.orderfile +2 -2
index ac699700b1..e89790941c 100644
@@ -19,11 +19,11 @@ Makefile*
 *.mak
 
 # qapi schema
-*.json
+qapi/*.json
+qga/*.json
 
 # headers
 *.h
 
 # code
 *.c
-
#38 lore raw

PATCH 14/17 qapi: Section parameter @indent is no longer used, drop

In reply to Markus Armbruster
---
 scripts/qapi/parser.py | 31 ++++++++++++++-----------------
 1 file changed, 14 insertions(+), 17 deletions(-)
scripts/qapi/parser.py +14 -17
index 3e29b7bf48..22ee631198 100644
@@ -468,8 +468,7 @@ class QAPIDoc:
     class Section:
         # pylint: disable=too-few-public-methods
         def __init__(self, parser: QAPISchemaParser,
-                     name: Optional[str] = None, indent: int = 0):
-
+                     name: Optional[str] = None):
             # parser, for error messages about indentation
             self._parser = parser
             # optional section name (argument/member or section name)
@@ -500,8 +499,8 @@ def append(self, line: str) -> None:
 
     class ArgSection(Section):
         def __init__(self, parser: QAPISchemaParser,
-                     name: str, indent: int = 0):
-            super().__init__(parser, name, indent)
+                     name: str):
+            super().__init__(parser, name)
             self.member: Optional['QAPISchemaMember'] = None
 
         def connect(self, member: 'QAPISchemaMember') -> None:
@@ -626,7 +625,7 @@ def _append_args_line(self, line: str) -> None:
         """
         if match := self._match_at_name_colon(line):
             line = line[match.end():]
-            self._start_args_section(match.group(1), 0)
+            self._start_args_section(match.group(1))
         elif self._match_section_tag(line):
             self._append_line = self._append_various_line
             self._append_various_line(line)
@@ -646,7 +645,7 @@ def _append_args_line(self, line: str) -> None:
     def _append_features_line(self, line: str) -> None:
         if match := self._match_at_name_colon(line):
             line = line[match.end():]
-            self._start_features_section(match.group(1), 0)
+            self._start_features_section(match.group(1))
         elif self._match_section_tag(line):
             self._append_line = self._append_various_line
             self._append_various_line(line)
@@ -677,15 +676,14 @@ def _append_various_line(self, line: str) -> None:
                                  % (match.group(1), self.sections[0].name))
         if match := self._match_section_tag(line):
             line = line[match.end():]
-            self._start_section(match.group(1), 0)
+            self._start_section(match.group(1))
 
         self._append_freeform(line)
 
     def _start_symbol_section(
             self,
             symbols_dict: Dict[str, 'QAPIDoc.ArgSection'],
-            name: str,
-            indent: int) -> None:
+            name: str) -> None:
         # FIXME invalid names other than the empty string aren't flagged
         if not name:
             raise QAPIParseError(self._parser, "invalid parameter name")
@@ -693,22 +691,21 @@ def _start_symbol_section(
             raise QAPIParseError(self._parser,
                                  "'%s' parameter name duplicated" % name)
         assert not self.sections
-        new_section = QAPIDoc.ArgSection(self._parser, name, indent)
+        new_section = QAPIDoc.ArgSection(self._parser, name)
         self._switch_section(new_section)
         symbols_dict[name] = new_section
 
-    def _start_args_section(self, name: str, indent: int) -> None:
-        self._start_symbol_section(self.args, name, indent)
+    def _start_args_section(self, name: str) -> None:
+        self._start_symbol_section(self.args, name)
 
-    def _start_features_section(self, name: str, indent: int) -> None:
-        self._start_symbol_section(self.features, name, indent)
+    def _start_features_section(self, name: str) -> None:
+        self._start_symbol_section(self.features, name)
 
-    def _start_section(self, name: Optional[str] = None,
-                       indent: int = 0) -> None:
+    def _start_section(self, name: Optional[str] = None) -> None:
         if name in ('Returns', 'Since') and self.has_section(name):
             raise QAPIParseError(self._parser,
                                  "duplicated '%s' section" % name)
-        new_section = QAPIDoc.Section(self._parser, name, indent)
+        new_section = QAPIDoc.Section(self._parser, name)
         self._switch_section(new_section)
         self.sections.append(new_section)
 
Signature · 1 line
2.39.2
#40 lore raw

PATCH 15/17 docs/devel/qapi-code-gen: Update doc comment conventions

In reply to Markus Armbruster

The commit before previous relaxed the indentation rules to let us improve the doc comment conventions. This commit changes the written conventions. The next commits will update QAPI schemas to conform to them.

---
 docs/devel/qapi-code-gen.rst | 46 +++++++++++++++++-------------------
 1 file changed, 22 insertions(+), 24 deletions(-)
docs/devel/qapi-code-gen.rst +22 -24
index 875f893be2..5618a80378 100644
@@ -947,6 +947,11 @@ Example::
  #   <- get that
  ##
 
+For legibility, wrap text paragraphs so every line is at most 70
+characters long.
+
+Separate sentences with two spaces.
+
 
 Definition documentation
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -963,22 +968,12 @@ 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.
 
-The description of an argument or feature 'name' starts with
-'\@name:'.  The description text can start on the line following the
-'\@name:', in which case it must not be indented at all.  It can also
-start on the same line as the '\@name:'.  In this case if it spans
-multiple lines then second and subsequent lines must be indented to
-line up with the first character of the first line of the
-description::
+Descriptions start with '\@name:'.  The description text should be
+indented like this::
 
- # @argone:
- # This is a two line description
- # in the first style.
- #
- # @argtwo: This is a two line description
- #          in the second style.
+ # @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
+ #     do eiusmod tempor incididunt ut labore et dolore magna aliqua.
 
-The number of spaces between the ':' and the text is not significant.
 .. FIXME The parser accepts these things in almost any order.
 
 .. FIXME union branches should be described, too.
@@ -990,23 +985,26 @@ The feature descriptions must be preceded by 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.
 
-The text of a section can start on a new line, in
-which case it must not be indented at all.  It can also start
-on the same line as the "Note:", "Returns:", etc tag.  In this
-case if it spans multiple lines then second and subsequent
-lines must be indented to match the first, in the same way as
-multiline argument descriptions.
+The second and subsequent lines of sections other than
+"Example"/"Examples" should be indented like this::
+
+ # Note: Ut enim ad minim veniam, quis nostrud exercitation ullamco
+ #     laboris nisi ut aliquip ex ea commodo consequat.
+ #
+ #     Duis aute irure dolor in reprehenderit in voluptate velit esse
+ #     cillum dolore eu fugiat nulla pariatur.
 
 A "Since: x.y.z" tagged section lists the release that introduced the
 definition.
 
-An "Example" or "Examples" section is automatically rendered entirely
+An "Example" or "Examples" section is rendered entirely
 as literal fixed-width text.  "TODO" sections are not rendered at all
 (they are for developers, not users of QMP).  In other sections, the
 text is formatted, and rST markup can be used.
@@ -1019,7 +1017,7 @@ For example::
  # Statistics of a virtual block device or a block backing device.
  #
  # @device: If the stats are for a virtual block device, the name
- #          corresponding to the virtual block device.
+ #     corresponding to the virtual block device.
  #
  # @node-name: The node name of the device. (since 2.3)
  #
@@ -1036,8 +1034,8 @@ For example::
  #
  # Query the @BlockStats for all virtual block devices.
  #
- # @query-nodes: If true, the command will query all the
- #               block nodes ... explain, explain ...  (since 2.3)
+ # @query-nodes: If true, the command will query all the block nodes
+ #     ... explain, explain ...  (since 2.3)
  #
  # Returns: A list of @BlockStats for each virtual block devices.
  #
Signature · 1 line
2.39.2
Reviewed-by on v1 15/17
#41 lore raw

Re: [PATCH 15/17] docs/devel/qapi-code-gen: Update doc comment conventions

Quoted 6 lines · Markus Armbruster

The commit before previous relaxed the indentation rules to let us improve the doc comment conventions. This commit changes the written conventions. The next commits will update QAPI schemas to conform to them.

#42 lore raw

PATCH 16/17 qga/qapi-schema: Reformat doc comments to conform to current conventions

In reply to Markus Armbruster

Change

# @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
# do eiusmod tempor incididunt ut labore et dolore magna aliqua.

to

# @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
# do eiusmod tempor incididunt ut labore et dolore magna aliqua.

See recent commit "qapi: Relax doc string @name: description indentation rules" for rationale.

Reflow paragraphs to 70 columns width, and consistently use two spaces to separate sentences.

To check the generated documentation does not change, I compared the generated HTML before and after this commit with "wdiff -3". Finds no differences. Comparing with diff is not useful, as the reflown paragraphs are visible there.

---
 qga/qapi-schema.json | 668 +++++++++++++++++++++++++------------------
 1 file changed, 382 insertions(+), 286 deletions(-)
qga/qapi-schema.json +382 -286
index 6a20eeb297..721a0baf3e 100644
@@ -4,10 +4,10 @@
 ##
 # = General note concerning the use of guest agent interfaces
 #
-# "unsupported" is a higher-level error than the errors that individual
-# commands might document. The caller should always be prepared to receive
-# QERR_UNSUPPORTED, even if the given command doesn't specify it, or doesn't
-# document any failure mode at all.
+# "unsupported" is a higher-level error than the errors that
+# individual commands might document.  The caller should always be
+# prepared to receive QERR_UNSUPPORTED, even if the given command
+# doesn't specify it, or doesn't document any failure mode at all.
 ##
 
 ##
@@ -38,28 +38,27 @@
 ##
 # @guest-sync-delimited:
 #
-# Echo back a unique integer value, and prepend to response a
-# leading sentinel byte (0xFF) the client can check scan for.
+# Echo back a unique integer value, and prepend to response a leading
+# sentinel byte (0xFF) the client can check scan for.
 #
-# This is used by clients talking to the guest agent over the
-# wire to ensure the stream is in sync and doesn't contain stale
-# data from previous client. It must be issued upon initial
-# connection, and after any client-side timeouts (including
-# timeouts on receiving a response to this command).
+# This is used by clients talking to the guest agent over the wire to
+# ensure the stream is in sync and doesn't contain stale data from
+# previous client.  It must be issued upon initial connection, and
+# after any client-side timeouts (including timeouts on receiving a
+# response to this command).
 #
 # After issuing this request, all guest agent responses should be
-# ignored until the response containing the unique integer value
-# the client passed in is returned. Receival of the 0xFF sentinel
-# byte must be handled as an indication that the client's
-# lexer/tokenizer/parser state should be flushed/reset in
-# preparation for reliably receiving the subsequent response. As
-# an optimization, clients may opt to ignore all data until a
-# sentinel value is receiving to avoid unnecessary processing of
-# stale data.
+# ignored until the response containing the unique integer value the
+# client passed in is returned.  Receival of the 0xFF sentinel byte
+# must be handled as an indication that the client's
+# lexer/tokenizer/parser state should be flushed/reset in preparation
+# for reliably receiving the subsequent response.  As an optimization,
+# clients may opt to ignore all data until a sentinel value is
+# receiving to avoid unnecessary processing of stale data.
 #
-# Similarly, clients should also precede this *request*
-# with a 0xFF byte to make sure the guest agent flushes any
-# partially read JSON data from a previous client connection.
+# Similarly, clients should also precede this *request* with a 0xFF
+# byte to make sure the guest agent flushes any partially read JSON
+# data from a previous client connection.
 #
 # @id: randomly generated 64-bit integer
 #
@@ -76,28 +75,27 @@
 #
 # Echo back a unique integer value
 #
-# This is used by clients talking to the guest agent over the
-# wire to ensure the stream is in sync and doesn't contain stale
-# data from previous client. All guest agent responses should be
-# ignored until the provided unique integer value is returned,
-# and it is up to the client to handle stale whole or
-# partially-delivered JSON text in such a way that this response
-# can be obtained.
+# This is used by clients talking to the guest agent over the wire to
+# ensure the stream is in sync and doesn't contain stale data from
+# previous client.  All guest agent responses should be ignored until
+# the provided unique integer value is returned, and it is up to the
+# client to handle stale whole or partially-delivered JSON text in
+# such a way that this response can be obtained.
 #
-# In cases where a partial stale response was previously
-# received by the client, this cannot always be done reliably.
-# One particular scenario being if qemu-ga responses are fed
-# character-by-character into a JSON parser. In these situations,
-# using guest-sync-delimited may be optimal.
+# In cases where a partial stale response was previously received by
+# the client, this cannot always be done reliably.  One particular
+# scenario being if qemu-ga responses are fed character-by-character
+# into a JSON parser.  In these situations, using guest-sync-delimited
+# may be optimal.
 #
-# For clients that fetch responses line by line and convert them
-# to JSON objects, guest-sync should be sufficient, but note that
-# in cases where the channel is dirty some attempts at parsing the
+# For clients that fetch responses line by line and convert them to
+# JSON objects, guest-sync should be sufficient, but note that in
+# cases where the channel is dirty some attempts at parsing the
 # response may result in a parser error.
 #
-# Such clients should also precede this command
-# with a 0xFF byte to make sure the guest agent flushes any
-# partially read JSON data from a previous session.
+# Such clients should also precede this command with a 0xFF byte to
+# make sure the guest agent flushes any partially read JSON data from
+# a previous session.
 #
 # @id: randomly generated 64-bit integer
 #
@@ -121,8 +119,8 @@
 ##
 # @guest-get-time:
 #
-# Get the information about guest's System Time relative to
-# the Epoch of 1970-01-01 in UTC.
+# Get the information about guest's System Time relative to the Epoch
+# of 1970-01-01 in UTC.
 #
 # Returns: Time in nanoseconds.
 #
@@ -136,23 +134,21 @@
 #
 # Set guest time.
 #
-# When a guest is paused or migrated to a file then loaded
-# from that file, the guest OS has no idea that there
-# was a big gap in the time. Depending on how long the
-# gap was, NTP might not be able to resynchronize the
-# guest.
+# When a guest is paused or migrated to a file then loaded from that
+# file, the guest OS has no idea that there was a big gap in the time.
+# Depending on how long the gap was, NTP might not be able to
+# resynchronize the guest.
 #
-# This command tries to set guest's System Time to the
-# given value, then sets the Hardware Clock (RTC) to the
-# current System Time. This will make it easier for a guest
-# to resynchronize without waiting for NTP. If no @time is
-# specified, then the time to set is read from RTC. However,
-# this may not be supported on all platforms (i.e. Windows).
-# If that's the case users are advised to always pass a
+# This command tries to set guest's System Time to the given value,
+# then sets the Hardware Clock (RTC) to the current System Time.  This
+# will make it easier for a guest to resynchronize without waiting for
+# NTP. If no @time is specified, then the time to set is read from
+# RTC. However, this may not be supported on all platforms (i.e.
+# Windows). If that's the case users are advised to always pass a
 # value.
 #
-# @time: time of nanoseconds, relative to the Epoch
-#        of 1970-01-01 in UTC.
+# @time: time of nanoseconds, relative to the Epoch of 1970-01-01 in
+#     UTC.
 #
 # Returns: Nothing on success.
 #
@@ -171,7 +167,7 @@
 # @enabled: whether command is currently enabled by guest admin
 #
 # @success-response: whether command returns a response on success
-#                    (since 1.7)
+#     (since 1.7)
 #
 # Since: 1.1.0
 ##
@@ -207,15 +203,15 @@
 ##
 # @guest-shutdown:
 #
-# Initiate guest-activated shutdown. Note: this is an asynchronous
+# Initiate guest-activated shutdown.  Note: this is an asynchronous
 # shutdown request, with no guarantee of successful shutdown.
 #
 # @mode: "halt", "powerdown" (default), or "reboot"
 #
-# This command does NOT return a response on success. Success condition
-# is indicated by the VM exiting with a zero exit status or, when
-# running with --no-shutdown, by issuing the query-status QMP command
-# to confirm the VM status is "shutdown".
+# This command does NOT return a response on success.  Success
+# condition is indicated by the VM exiting with a zero exit status or,
+# when running with --no-shutdown, by issuing the query-status QMP
+# command to confirm the VM status is "shutdown".
 #
 # Since: 0.15.0
 ##
@@ -259,7 +255,7 @@
 # Result of guest agent file-read operation
 #
 # @count: number of bytes read (note: count is *before*
-#         base64-encoding is applied)
+#     base64-encoding is applied)
 #
 # @buf-b64: base64-encoded bytes read
 #
@@ -273,13 +269,14 @@
 ##
 # @guest-file-read:
 #
-# Read from an open file in the guest. Data will be base64-encoded.
+# Read from an open file in the guest.  Data will be base64-encoded.
 # As this command is just for limited, ad-hoc debugging, such as log
 # file access, the number of bytes to read is limited to 48 MB.
 #
 # @handle: filehandle returned by guest-file-open
 #
-# @count: maximum number of bytes to read (default is 4KB, maximum is 48MB)
+# @count: maximum number of bytes to read (default is 4KB, maximum is
+#     48MB)
 #
 # Returns: @GuestFileRead on success.
 #
@@ -295,7 +292,7 @@
 # Result of guest agent file-write operation
 #
 # @count: number of bytes written (note: count is actual bytes
-#         written, after base64-decoding of provided buffer)
+#     written, after base64-decoding of provided buffer)
 #
 # @eof: whether EOF was encountered during write operation.
 #
@@ -313,8 +310,8 @@
 #
 # @buf-b64: base64-encoded string representing data to be written
 #
-# @count: bytes to write (actual bytes, after base64-decode),
-#         default is all content in buf-b64 buffer after base64 decoding
+# @count: bytes to write (actual bytes, after base64-decode), default
+#     is all content in buf-b64 buffer after base64 decoding
 #
 # Returns: @GuestFileWrite on success.
 #
@@ -345,7 +342,9 @@
 # Symbolic names for use in @guest-file-seek
 #
 # @set: Set to the specified offset (same effect as 'whence':0)
+#
 # @cur: Add offset to the current location (same effect as 'whence':1)
+#
 # @end: Add offset to the end of the file (same effect as 'whence':2)
 #
 # Since: 2.6
@@ -358,8 +357,9 @@
 # Controls the meaning of offset to @guest-file-seek.
 #
 # @value: Integral value (0 for set, 1 for cur, 2 for end), available
-#         for historical reasons, and might differ from the host's or
-#         guest's SEEK_* values (since: 0.15)
+#     for historical reasons, and might differ from the host's or
+#     guest's SEEK_* values (since: 0.15)
+#
 # @name: Symbolic name, and preferred interface
 #
 # Since: 2.6
@@ -371,7 +371,7 @@
 # @guest-file-seek:
 #
 # Seek to a position in the file, as with fseek(), and return the
-# current file position afterward. Also encapsulates ftell()'s
+# current file position afterward.  Also encapsulates ftell()'s
 # functionality, with offset=0 and whence=1.
 #
 # @handle: filehandle returned by guest-file-open
@@ -422,10 +422,11 @@
 #
 # Get guest fsfreeze state.
 #
-# Returns: GuestFsfreezeStatus ("thawed", "frozen", etc., as defined below)
+# Returns: GuestFsfreezeStatus ("thawed", "frozen", etc., as defined
+#     below)
 #
-# Note: This may fail to properly report the current state as a result of
-#       some other guest processes having issued an fs freeze/thaw.
+# Note: This may fail to properly report the current state as a result
+#     of some other guest processes having issued an fs freeze/thaw.
 #
 # Since: 0.15.0
 ##
@@ -435,18 +436,18 @@
 ##
 # @guest-fsfreeze-freeze:
 #
-# Sync and freeze all freezable, local guest filesystems. If this
+# Sync and freeze all freezable, local guest filesystems.  If this
 # command succeeded, you may call @guest-fsfreeze-thaw later to
 # unfreeze.
 #
 # Note: On Windows, the command is implemented with the help of a
-#       Volume Shadow-copy Service DLL helper. The frozen state is limited
-#       for up to 10 seconds by VSS.
+#     Volume Shadow-copy Service DLL helper.  The frozen state is
+#     limited for up to 10 seconds by VSS.
 #
-# Returns: Number of file systems currently frozen. On error, all filesystems
-#          will be thawed. If no filesystems are frozen as a result of this call,
-#          then @guest-fsfreeze-status will remain "thawed" and calling
-#          @guest-fsfreeze-thaw is not necessary.
+# Returns: Number of file systems currently frozen.  On error, all
+#     filesystems will be thawed.  If no filesystems are frozen as a
+#     result of this call, then @guest-fsfreeze-status will remain
+#     "thawed" and calling @guest-fsfreeze-thaw is not necessary.
 #
 # Since: 0.15.0
 ##
@@ -456,15 +457,15 @@
 ##
 # @guest-fsfreeze-freeze-list:
 #
-# Sync and freeze specified guest filesystems.
-# See also @guest-fsfreeze-freeze.
+# Sync and freeze specified guest filesystems.  See also
+# @guest-fsfreeze-freeze.
 #
 # @mountpoints: an array of mountpoints of filesystems to be frozen.
-#               If omitted, every mounted filesystem is frozen.
-#               Invalid mount points are ignored.
+#     If omitted, every mounted filesystem is frozen.  Invalid mount
+#     points are ignored.
 #
-# Returns: Number of file systems currently frozen. On error, all filesystems
-#          will be thawed.
+# Returns: Number of file systems currently frozen.  On error, all
+#     filesystems will be thawed.
 #
 # Since: 2.2
 ##
@@ -480,10 +481,9 @@
 # Returns: Number of file systems thawed by this call
 #
 # Note: if return value does not match the previous call to
-#       guest-fsfreeze-freeze, this likely means some freezable
-#       filesystems were unfrozen before this call, and that the
-#       filesystem state may have changed before issuing this
-#       command.
+#     guest-fsfreeze-freeze, this likely means some freezable
+#     filesystems were unfrozen before this call, and that the
+#     filesystem state may have changed before issuing this command.
 #
 # Since: 0.15.0
 ##
@@ -494,8 +494,11 @@
 # @GuestFilesystemTrimResult:
 #
 # @path: path that was trimmed
+#
 # @error: an error message when trim failed
+#
 # @trimmed: bytes trimmed for this path
+#
 # @minimum: reported effective minimum for this path
 #
 # Since: 2.4
@@ -519,15 +522,16 @@
 #
 # Discard (or "trim") blocks which are not in use by the filesystem.
 #
-# @minimum: Minimum contiguous free range to discard, in bytes. Free ranges
-#           smaller than this may be ignored (this is a hint and the guest
-#           may not respect it).  By increasing this value, the fstrim
-#           operation will complete more quickly for filesystems with badly
-#           fragmented free space, although not all blocks will be discarded.
-#           The default value is zero, meaning "discard every free block".
+# @minimum: Minimum contiguous free range to discard, in bytes.  Free
+#     ranges smaller than this may be ignored (this is a hint and the
+#     guest may not respect it).  By increasing this value, the fstrim
+#     operation will complete more quickly for filesystems with badly
+#     fragmented free space, although not all blocks will be
+#     discarded.  The default value is zero, meaning "discard every
+#     free block".
 #
-# Returns: A @GuestFilesystemTrimResponse which contains the
-#          status of all trimmed paths. (since 2.4)
+# Returns: A @GuestFilesystemTrimResponse which contains the status of
+#     all trimmed paths.  (since 2.4)
 #
 # Since: 1.2
 ##
@@ -540,25 +544,26 @@
 #
 # Suspend guest to disk.
 #
-# This command attempts to suspend the guest using three strategies, in this
-# order:
+# This command attempts to suspend the guest using three strategies,
+# in this order:
 #
 # - systemd hibernate
 # - pm-utils (via pm-hibernate)
 # - manual write into sysfs
 #
-# This command does NOT return a response on success. There is a high chance
-# the command succeeded if the VM exits with a zero exit status or, when
-# running with --no-shutdown, by issuing the query-status QMP command to
-# to confirm the VM status is "shutdown". However, the VM could also exit
-# (or set its status to "shutdown") due to other reasons.
+# This command does NOT return a response on success.  There is a high
+# chance the command succeeded if the VM exits with a zero exit status
+# or, when running with --no-shutdown, by issuing the query-status QMP
+# command to to confirm the VM status is "shutdown". However, the VM
+# could also exit (or set its status to "shutdown") due to other
+# reasons.
 #
 # The following errors may be returned:
 #
 # - If suspend to disk is not supported, Unsupported
 #
-# Notes: It's strongly recommended to issue the guest-sync command before
-#        sending commands when the guest resumes
+# Notes: It's strongly recommended to issue the guest-sync command
+#     before sending commands when the guest resumes
 #
 # Since: 1.1
 ##
@@ -569,21 +574,22 @@
 #
 # Suspend guest to ram.
 #
-# This command attempts to suspend the guest using three strategies, in this
-# order:
+# This command attempts to suspend the guest using three strategies,
+# in this order:
 #
-# - systemd suspend
-# - pm-utils (via pm-suspend)
+# - systemd hibernate
+# - pm-utils (via pm-hibernate)
 # - manual write into sysfs
 #
 # IMPORTANT: guest-suspend-ram requires working wakeup support in
 # QEMU. You should check QMP command query-current-machine returns
-# wakeup-suspend-support: true before issuing this command. Failure in
-# doing so can result in a suspended guest that QEMU will not be able to
-# awaken, forcing the user to power cycle the guest to bring it back.
+# wakeup-suspend-support: true before issuing this command.  Failure
+# in doing so can result in a suspended guest that QEMU will not be
+# able to awaken, forcing the user to power cycle the guest to bring
+# it back.
 #
-# This command does NOT return a response on success. There are two options
-# to check for success:
+# This command does NOT return a response on success.  There are two
+# options to check for success:
 #
 # 1. Wait for the SUSPEND QMP event from QEMU
 # 2. Issue the query-status QMP command to confirm the VM status is
@@ -593,8 +599,8 @@
 #
 # - If suspend to ram is not supported, Unsupported
 #
-# Notes: It's strongly recommended to issue the guest-sync command before
-#        sending commands when the guest resumes
+# Notes: It's strongly recommended to issue the guest-sync command
+#     before sending commands when the guest resumes
 #
 # Since: 1.1
 ##
@@ -605,19 +611,21 @@
 #
 # Save guest state to disk and suspend to ram.
 #
-# This command attempts to suspend the guest by executing, in this order:
+# This command attempts to suspend the guest by executing, in this
+# order:
 #
 # - systemd hybrid-sleep
 # - pm-utils (via pm-suspend-hybrid)
 #
 # IMPORTANT: guest-suspend-hybrid requires working wakeup support in
 # QEMU. You should check QMP command query-current-machine returns
-# wakeup-suspend-support: true before issuing this command. Failure in
-# doing so can result in a suspended guest that QEMU will not be able to
-# awaken, forcing the user to power cycle the guest to bring it back.
+# wakeup-suspend-support: true before issuing this command.  Failure
+# in doing so can result in a suspended guest that QEMU will not be
+# able to awaken, forcing the user to power cycle the guest to bring
+# it back.
 #
-# This command does NOT return a response on success. There are two options
-# to check for success:
+# This command does NOT return a response on success.  There are two
+# options to check for success:
 #
 # 1. Wait for the SUSPEND QMP event from QEMU
 # 2. Issue the query-status QMP command to confirm the VM status is
@@ -627,8 +635,8 @@
 #
 # - If hybrid suspend is not supported, Unsupported
 #
-# Notes: It's strongly recommended to issue the guest-sync command before
-#        sending commands when the guest resumes
+# Notes: It's strongly recommended to issue the guest-sync command
+#     before sending commands when the guest resumes
 #
 # Since: 1.1
 ##
@@ -705,8 +713,8 @@
 #
 # @ip-addresses: List of addresses assigned to @name
 #
-# @statistics: various statistic counters related to @name
-#              (since 2.11)
+# @statistics: various statistic counters related to @name (since
+#     2.11)
 #
 # Since: 1.1
 ##
@@ -719,8 +727,7 @@
 ##
 # @guest-network-get-interfaces:
 #
-# Get list of guest IP addresses, MAC addresses
-# and netmasks.
+# Get list of guest IP addresses, MAC addresses and netmasks.
 #
 # Returns: List of GuestNetworkInterface on success.
 #
@@ -736,10 +743,10 @@
 #
 # @online: Whether the VCPU is enabled.
 #
-# @can-offline: Whether offlining the VCPU is possible. This member
-#               is always filled in by the guest agent when the structure is
-#               returned, and always ignored on input (hence it can be omitted
-#               then).
+# @can-offline: Whether offlining the VCPU is possible.  This member
+#     is always filled in by the guest agent when the structure is
+#     returned, and always ignored on input (hence it can be omitted
+#     then).
 #
 # Since: 1.5
 ##
@@ -755,8 +762,8 @@
 #
 # This is a read-only operation.
 #
-# Returns: The list of all VCPUs the guest knows about. Each VCPU is put on the
-#          list exactly once, but their order is unspecified.
+# Returns: The list of all VCPUs the guest knows about.  Each VCPU is
+#     put on the list exactly once, but their order is unspecified.
 #
 # Since: 1.5
 ##
@@ -766,36 +773,36 @@
 ##
 # @guest-set-vcpus:
 #
-# Attempt to reconfigure (currently: enable/disable) logical processors inside
-# the guest.
+# Attempt to reconfigure (currently: enable/disable) logical
+# processors inside the guest.
 #
-# The input list is processed node by node in order. In each node @logical-id
-# is used to look up the guest VCPU, for which @online specifies the requested
-# state. The set of distinct @logical-id's is only required to be a subset of
-# the guest-supported identifiers. There's no restriction on list length or on
-# repeating the same @logical-id (with possibly different @online field).
-# Preferably the input list should describe a modified subset of
-# @guest-get-vcpus' return value.
+# The input list is processed node by node in order.  In each node
+# @logical-id is used to look up the guest VCPU, for which @online
+# specifies the requested state.  The set of distinct @logical-id's is
+# only required to be a subset of the guest-supported identifiers.
+# There's no restriction on list length or on repeating the same
+# @logical-id (with possibly different @online field). Preferably the
+# input list should describe a modified subset of @guest-get-vcpus'
+# return value.
 #
-# Returns: The length of the initial sublist that has been successfully
-#          processed. The guest agent maximizes this value. Possible cases:
+# Returns: The length of the initial sublist that has been
+#     successfully processed.  The guest agent maximizes this value.
+#     Possible cases:
 #
-#          - 0:
-#            if the @vcpus list was empty on input. Guest state
-#            has not been changed. Otherwise,
-#          - Error:
-#            processing the first node of @vcpus failed for the
-#            reason returned. Guest state has not been changed.
-#            Otherwise,
-#          - < length(@vcpus):
-#            more than zero initial nodes have been processed,
-#            but not the entire @vcpus list. Guest state has
-#            changed accordingly. To retrieve the error
-#            (assuming it persists), repeat the call with the
-#            successfully processed initial sublist removed.
-#            Otherwise,
-#          - length(@vcpus):
-#            call successful.
+#     - 0:
+#       if the @vcpus list was empty on input.  Guest state has not
+#       been changed.  Otherwise,
+#     - Error:
+#       processing the first node of @vcpus failed for the reason
+#       returned.  Guest state has not been changed.  Otherwise,
+#     - < length(@vcpus):
+#       more than zero initial nodes have been processed, but not the
+#       entire @vcpus list.  Guest state has changed accordingly.  To
+#       retrieve the error (assuming it persists), repeat the call
+#       with the successfully processed initial sublist removed.
+#       Otherwise,
+#     - length(@vcpus):
+#       call successful.
 #
 # Since: 1.5
 ##
@@ -809,24 +816,43 @@
 # An enumeration of bus type of disks
 #
 # @ide: IDE disks
+#
 # @fdc: floppy disks
+#
 # @scsi: SCSI disks
+#
 # @virtio: virtio disks
+#
 # @xen: Xen disks
+#
 # @usb: USB disks
+#
 # @uml: UML disks
+#
 # @sata: SATA disks
+#
 # @sd: SD cards
+#
 # @unknown: Unknown bus type
+#
 # @ieee1394: Win IEEE 1394 bus type
+#
 # @ssa: Win SSA bus type
+#
 # @fibre: Win fiber channel bus type
+#
 # @raid: Win RAID bus type
+#
 # @iscsi: Win iScsi bus type
+#
 # @sas: Win serial-attaches SCSI bus type
+#
 # @mmc: Win multimedia card (MMC) bus type
+#
 # @virtual: Win virtual bus type
+#
 # @file-backed-virtual: Win file-backed bus type
+#
 # @nvme: NVMe disks (since 7.1)
 #
 # Since: 2.2; 'Unknown' and all entries below since 2.4
@@ -841,8 +867,11 @@
 # @GuestPCIAddress:
 #
 # @domain: domain id
+#
 # @bus: bus id
+#
 # @slot: slot id
+#
 # @function: function id
 #
 # Since: 2.2
@@ -855,8 +884,11 @@
 # @GuestCCWAddress:
 #
 # @cssid: channel subsystem image id
+#
 # @ssid: subchannel set id
+#
 # @subchno: subchannel number
+#
 # @devno: device number
 #
 # Since: 6.0
@@ -870,13 +902,21 @@
 ##
 # @GuestDiskAddress:
 #
-# @pci-controller: controller's PCI address (fields are set to -1 if invalid)
+# @pci-controller: controller's PCI address (fields are set to -1 if
+#     invalid)
+#
 # @bus-type: bus type
+#
 # @bus: bus id
+#
 # @target: target id
+#
 # @unit: unit id
+#
 # @serial: serial number (since: 3.1)
+#
 # @dev: device node (POSIX) or device UNC (Windows) (since: 3.1)
+#
 # @ccw-address: CCW address on s390x (since: 6.0)
 #
 # Since: 2.2
@@ -891,8 +931,8 @@
 ##
 # @GuestNVMeSmart:
 #
-# NVMe smart informations, based on NVMe specification,
-# section <SMART / Health Information (Log Identifier 02h)>
+# NVMe smart informations, based on NVMe specification, section
+# <SMART / Health Information (Log Identifier 02h)>
 #
 # Since: 7.1
 ##
@@ -941,13 +981,18 @@
 # @GuestDiskInfo:
 #
 # @name: device node (Linux) or device UNC (Windows)
+#
 # @partition: whether this is a partition or disk
-# @dependencies: list of device dependencies; e.g. for LVs of the LVM this will
-#                hold the list of PVs, for LUKS encrypted volume this will
-#                contain the disk where the volume is placed.     (Linux)
+#
+# @dependencies: list of device dependencies; e.g. for LVs of the LVM
+#     this will hold the list of PVs, for LUKS encrypted volume this
+#     will contain the disk where the volume is placed.  (Linux)
+#
 # @address: disk address information (only for non-virtual devices)
-# @alias: optional alias assigned to the disk, on Linux this is a name assigned
-#         by device mapper
+#
+# @alias: optional alias assigned to the disk, on Linux this is a name
+#     assigned by device mapper
+#
 # @smart: disk smart information (Since 7.1)
 #
 # Since: 5.2
@@ -960,10 +1005,10 @@
 ##
 # @guest-get-disks:
 #
-# Returns: The list of disks in the guest. For Windows these are only the
-#          physical disks. On Linux these are all root block devices of
-#          non-zero size including e.g. removable devices, loop devices,
-#          NBD, etc.
+# Returns: The list of disks in the guest.  For Windows these are only
+#     the physical disks.  On Linux these are all root block devices
+#     of non-zero size including e.g. removable devices, loop devices,
+#     NBD, etc.
 #
 # Since: 5.2
 ##
@@ -974,12 +1019,17 @@
 # @GuestFilesystemInfo:
 #
 # @name: disk name
+#
 # @mountpoint: mount point path
+#
 # @type: file system type string
+#
 # @used-bytes: file system used bytes (since 3.0)
+#
 # @total-bytes: non-root file system total bytes (since 3.0)
-# @disk: an array of disk hardware information that the volume lies on,
-#        which may be empty if the disk type is not supported
+#
+# @disk: an array of disk hardware information that the volume lies
+#     on, which may be empty if the disk type is not supported
 #
 # Since: 2.2
 ##
@@ -992,9 +1042,9 @@
 # @guest-get-fsinfo:
 #
 # Returns: The list of filesystems information mounted in the guest.
-#          The returned mountpoints may be specified to
-#          @guest-fsfreeze-freeze-list.
-#          Network filesystems (such as CIFS and NFS) are not listed.
+#     The returned mountpoints may be specified to
+#     @guest-fsfreeze-freeze-list.  Network filesystems (such as CIFS
+#     and NFS) are not listed.
 #
 # Since: 2.2
 ##
@@ -1005,21 +1055,23 @@
 # @guest-set-user-password:
 #
 # @username: the user account whose password to change
+#
 # @password: the new password entry string, base64 encoded
+#
 # @crypted: true if password is already crypt()d, false if raw
 #
-# If the @crypted flag is true, it is the caller's responsibility
-# to ensure the correct crypt() encryption scheme is used. This
-# command does not attempt to interpret or report on the encryption
-# scheme. Refer to the documentation of the guest operating system
-# in question to determine what is supported.
+# If the @crypted flag is true, it is the caller's responsibility to
+# ensure the correct crypt() encryption scheme is used.  This command
+# does not attempt to interpret or report on the encryption scheme.
+# Refer to the documentation of the guest operating system in question
+# to determine what is supported.
 #
-# Not all guest operating systems will support use of the
-# @crypted flag, as they may require the clear-text password
+# Not all guest operating systems will support use of the @crypted
+# flag, as they may require the clear-text password
 #
 # The @password parameter must always be base64 encoded before
-# transmission, even if already crypt()d, to ensure it is 8-bit
-# safe when passed as JSON.
+# transmission, even if already crypt()d, to ensure it is 8-bit safe
+# when passed as JSON.
 #
 # Returns: Nothing on success.
 #
@@ -1031,14 +1083,15 @@
 ##
 # @GuestMemoryBlock:
 #
-# @phys-index: Arbitrary guest-specific unique identifier of the MEMORY BLOCK.
+# @phys-index: Arbitrary guest-specific unique identifier of the
+#     MEMORY BLOCK.
 #
 # @online: Whether the MEMORY BLOCK is enabled in guest.
 #
-# @can-offline: Whether offlining the MEMORY BLOCK is possible.
-#               This member is always filled in by the guest agent when the
-#               structure is returned, and always ignored on input (hence it
-#               can be omitted then).
+# @can-offline: Whether offlining the MEMORY BLOCK is possible.  This
+#     member is always filled in by the guest agent when the structure
+#     is returned, and always ignored on input (hence it can be
+#     omitted then).
 #
 # Since: 2.3
 ##
@@ -1054,9 +1107,9 @@
 #
 # This is a read-only operation.
 #
-# Returns: The list of all memory blocks the guest knows about.
-#          Each memory block is put on the list exactly once, but their order
-#          is unspecified.
+# Returns: The list of all memory blocks the guest knows about.  Each
+#     memory block is put on the list exactly once, but their order is
+#     unspecified.
 #
 # Since: 2.3
 ##
@@ -1068,12 +1121,17 @@
 #
 # An enumeration of memory block operation result.
 #
-# @success: the operation of online/offline memory block is successful.
-# @not-found: can't find the corresponding memoryXXX directory in sysfs.
+# @success: the operation of online/offline memory block is
+#     successful.
+#
+# @not-found: can't find the corresponding memoryXXX directory in
+#     sysfs.
+#
 # @operation-not-supported: for some old kernels, it does not support
-#                           online or offline memory block.
-# @operation-failed: the operation of online/offline memory block fails,
-#                    because of some errors happen.
+#     online or offline memory block.
+#
+# @operation-failed: the operation of online/offline memory block
+#     fails, because of some errors happen.
 #
 # Since: 2.3
 ##
@@ -1088,10 +1146,9 @@
 #
 # @response: the result of memory block operation.
 #
-# @error-code: the error number.
-#              When memory block operation fails, we assign the value of
-#              'errno' to this member, it indicates what goes wrong.
-#              When the operation succeeds, it will be omitted.
+# @error-code: the error number.  When memory block operation fails,
+#     we assign the value of 'errno' to this member, it indicates what
+#     goes wrong.  When the operation succeeds, it will be omitted.
 #
 # Since: 2.3
 ##
@@ -1103,24 +1160,25 @@
 ##
 # @guest-set-memory-blocks:
 #
-# Attempt to reconfigure (currently: enable/disable) state of memory blocks
-# inside the guest.
+# Attempt to reconfigure (currently: enable/disable) state of memory
+# blocks inside the guest.
 #
-# The input list is processed node by node in order. In each node @phys-index
-# is used to look up the guest MEMORY BLOCK, for which @online specifies the
-# requested state. The set of distinct @phys-index's is only required to be a
-# subset of the guest-supported identifiers. There's no restriction on list
-# length or on repeating the same @phys-index (with possibly different @online
-# field).
+# The input list is processed node by node in order.  In each node
+# @phys-index is used to look up the guest MEMORY BLOCK, for which
+# @online specifies the requested state.  The set of distinct
+# @phys-index's is only required to be a subset of the guest-supported
+# identifiers.  There's no restriction on list length or on repeating
+# the same @phys-index (with possibly different @online field).
 # Preferably the input list should describe a modified subset of
 # @guest-get-memory-blocks' return value.
 #
-# Returns: The operation results, it is a list of @GuestMemoryBlockResponse,
-#          which is corresponding to the input list.
+# Returns: The operation results, it is a list of
+#     @GuestMemoryBlockResponse, which is corresponding to the input
+#     list.
 #
-#          Note: it will return NULL if the @mem-blks list was empty on input,
-#          or there is an error, and in this case, guest state will not be
-#          changed.
+#     Note: it will return NULL if the @mem-blks list was empty on
+#     input, or there is an error, and in this case, guest state will
+#     not be changed.
 #
 # Since: 2.3
 ##
@@ -1131,9 +1189,9 @@
 ##
 # @GuestMemoryBlockInfo:
 #
-# @size: the size (in bytes) of the guest memory blocks,
-#        which are the minimal units of memory block online/offline
-#        operations (also called Logical Memory Hotplug).
+# @size: the size (in bytes) of the guest memory blocks, which are the
+#     minimal units of memory block online/offline operations (also
+#     called Logical Memory Hotplug).
 #
 # Since: 2.3
 ##
@@ -1156,17 +1214,23 @@
 # @GuestExecStatus:
 #
 # @exited: true if process has already terminated.
+#
 # @exitcode: process exit code if it was normally terminated.
-# @signal: signal number (linux) or unhandled exception code
-#          (windows) if the process was abnormally terminated.
+#
+# @signal: signal number (linux) or unhandled exception code (windows)
+#     if the process was abnormally terminated.
+#
 # @out-data: base64-encoded stdout of the process
-# @err-data: base64-encoded stderr of the process
-#            Note: @out-data and @err-data are present only
-#            if 'capture-output' was specified for 'guest-exec'
-# @out-truncated: true if stdout was not fully captured
-#                 due to size limitation.
-# @err-truncated: true if stderr was not fully captured
-#                 due to size limitation.
+#
+# @err-data: base64-encoded stderr of the process Note: @out-data and
+#     @err-data are present only if 'capture-output' was specified for
+#     'guest-exec'
+#
+# @out-truncated: true if stdout was not fully captured due to size
+#     limitation.
+#
+# @err-truncated: true if stderr was not fully captured due to size
+#     limitation.
 #
 # Since: 2.5
 ##
@@ -1177,8 +1241,9 @@
 ##
 # @guest-exec-status:
 #
-# Check status of process associated with PID retrieved via guest-exec.
-# Reap the process and associated metadata if it has exited.
+# Check status of process associated with PID retrieved via
+# guest-exec.  Reap the process and associated metadata if it has
+# exited.
 #
 # @pid: pid returned from guest-exec
 #
@@ -1206,11 +1271,15 @@
 # Execute a command in the guest
 #
 # @path: path or executable name to execute
+#
 # @arg: argument list to pass to executable
+#
 # @env: environment variables to pass to executable
+#
 # @input-data: data to be passed to process stdin (base64 encoded)
-# @capture-output: bool flag to enable capture of
-#                  stdout/stderr of running process. defaults to false.
+#
+# @capture-output: bool flag to enable capture of stdout/stderr of
+#     running process.  defaults to false.
 #
 # Returns: PID on success.
 #
@@ -1237,9 +1306,9 @@
 #
 # Return a name for the machine.
 #
-# The returned name is not necessarily a fully-qualified domain name, or even
-# present in DNS or some other name service at all. It need not even be unique
-# on your local network or site, but usually it is.
+# The returned name is not necessarily a fully-qualified domain name,
+# or even present in DNS or some other name service at all.  It need
+# not even be unique on your local network or site, but usually it is.
 #
 # Returns: the host name of the machine on success
 #
@@ -1253,10 +1322,13 @@
 # @GuestUser:
 #
 # @user: Username
+#
 # @domain: Logon domain (windows only)
-# @login-time: Time of login of this user on the computer. If multiple
-#              instances of the user are logged in, the earliest login time is
-#              reported. The value is in fractional seconds since epoch time.
+#
+# @login-time: Time of login of this user on the computer.  If
+#     multiple instances of the user are logged in, the earliest login
+#     time is reported.  The value is in fractional seconds since
+#     epoch time.
 #
 # Since: 2.10
 ##
@@ -1265,6 +1337,7 @@
 
 ##
 # @guest-get-users:
+#
 # Retrieves a list of currently active users on the VM.
 #
 # Returns: A unique list of users.
@@ -1277,10 +1350,11 @@
 ##
 # @GuestTimezone:
 #
-# @zone: Timezone name. These values may differ depending on guest/OS and
-#        should only be used for informational purposes.
-# @offset: Offset to UTC in seconds, negative numbers for time zones west of
-#          GMT, positive numbers for east
+# @zone: Timezone name.  These values may differ depending on guest/OS
+#     and should only be used for informational purposes.
+#
+# @offset: Offset to UTC in seconds, negative numbers for time zones
+#     west of GMT, positive numbers for east
 #
 # Since: 2.10
 ##
@@ -1303,45 +1377,56 @@
 # @GuestOSInfo:
 #
 # @kernel-release:
-# * POSIX: release field returned by uname(2)
-# * Windows: build number of the OS
+#     * POSIX: release field returned by uname(2)
+#     * Windows: build number of the OS
+#
 # @kernel-version:
-# * POSIX: version field returned by uname(2)
-# * Windows: version number of the OS
+#     * POSIX: version field returned by uname(2)
+#     * Windows: version number of the OS
+#
 # @machine:
-# * POSIX: machine field returned by uname(2)
-# * Windows: one of x86, x86_64, arm, ia64
+#     * POSIX: machine field returned by uname(2)
+#     * Windows: one of x86, x86_64, arm, ia64
+#
 # @id:
-# * POSIX: as defined by os-release(5)
-# * Windows: contains string "mswindows"
+#     * POSIX: as defined by os-release(5)
+#     * Windows: contains string "mswindows"
+#
 # @name:
-# * POSIX: as defined by os-release(5)
-# * Windows: contains string "Microsoft Windows"
+#     * POSIX: as defined by os-release(5)
+#     * Windows: contains string "Microsoft Windows"
+#
 # @pretty-name:
-# * POSIX: as defined by os-release(5)
-# * Windows: product name, e.g. "Microsoft Windows 10 Enterprise"
+#     * POSIX: as defined by os-release(5)
+#     * Windows: product name, e.g. "Microsoft Windows 10 Enterprise"
+#
 # @version:
-# * POSIX: as defined by os-release(5)
-# * Windows: long version string, e.g. "Microsoft Windows Server 2008"
+#     * POSIX: as defined by os-release(5)
+#     * Windows: long version string, e.g. "Microsoft Windows Server
+#       2008"
+#
 # @version-id:
-# * POSIX: as defined by os-release(5)
-# * Windows: short version identifier, e.g. "7" or "20012r2"
+#     * POSIX: as defined by os-release(5)
+#     * Windows: short version identifier, e.g. "7" or "20012r2"
+#
 # @variant:
-# * POSIX: as defined by os-release(5)
-# * Windows: contains string "server" or "client"
+#     * POSIX: as defined by os-release(5)
+#     * Windows: contains string "server" or "client"
+#
 # @variant-id:
-# * POSIX: as defined by os-release(5)
-# * Windows: contains string "server" or "client"
+#     * POSIX: as defined by os-release(5)
+#     * Windows: contains string "server" or "client"
 #
-# Notes:
+# Notes: On POSIX systems the fields @id, @name, @pretty-name,
+#     @version, @version-id, @variant and @variant-id follow the
+#     definition specified in os-release(5). Refer to the manual page
+#     for exact description of the fields.  Their values are taken
+#     from the os-release file.  If the file is not present in the
+#     system, or the values are not present in the file, the fields
+#     are not included.
 #
-# On POSIX systems the fields @id, @name, @pretty-name, @version, @version-id,
-# @variant and @variant-id follow the definition specified in os-release(5).
-# Refer to the manual page for exact description of the fields. Their values
-# are taken from the os-release file. If the file is not present in the system,
-# or the values are not present in the file, the fields are not included.
-#
-# On Windows the values are filled from information gathered from the system.
+#     On Windows the values are filled from information gathered from
+#     the system.
 #
 # Since: 2.10
 ##
@@ -1374,6 +1459,7 @@
 # @GuestDeviceIdPCI:
 #
 # @vendor-id: vendor ID
+#
 # @device-id: device ID
 #
 # Since: 5.2
@@ -1384,8 +1470,7 @@
 ##
 # @GuestDeviceId:
 #
-# Id of the device
-# - @pci: PCI ID, since: 5.2
+# Id of the device - @pci: PCI ID, since: 5.2
 #
 # Since: 5.2
 ##
@@ -1398,8 +1483,11 @@
 # @GuestDeviceInfo:
 #
 # @driver-name: name of the associated driver
+#
 # @driver-date: driver release date, in nanoseconds since the epoch
+#
 # @driver-version: driver version
+#
 # @id: device ID
 #
 # Since: 5.2
@@ -1443,8 +1531,8 @@
 #
 # @username: the user account to add the authorized keys
 #
-# Return the public keys from user .ssh/authorized_keys on Unix systems (not
-# implemented for other systems).
+# Return the public keys from user .ssh/authorized_keys on Unix
+# systems (not implemented for other systems).
 #
 # Returns: @GuestAuthorizedKeys
 #
@@ -1459,7 +1547,10 @@
 # @guest-ssh-add-authorized-keys:
 #
 # @username: the user account to add the authorized keys
-# @keys: the public keys to add (in OpenSSH/sshd(8) authorized_keys format)
+#
+# @keys: the public keys to add (in OpenSSH/sshd(8) authorized_keys
+#     format)
+#
 # @reset: ignore the existing content, set it with the given keys only
 #
 # Append public keys to user .ssh/authorized_keys on Unix systems (not
@@ -1477,11 +1568,13 @@
 # @guest-ssh-remove-authorized-keys:
 #
 # @username: the user account to remove the authorized keys
-# @keys: the public keys to remove (in OpenSSH/sshd(8) authorized_keys format)
 #
-# Remove public keys from the user .ssh/authorized_keys on Unix systems (not
-# implemented for other systems). It's not an error if the key is already
-# missing.
+# @keys: the public keys to remove (in OpenSSH/sshd(8) authorized_keys
+#     format)
+#
+# Remove public keys from the user .ssh/authorized_keys on Unix
+# systems (not implemented for other systems). It's not an error if
+# the key is already missing.
 #
 # Returns: Nothing on success.
 #
@@ -1526,7 +1619,8 @@
 #
 # @total-ticks: time spent doing I/Os (ms)
 #
-# @weight-ticks: weighted time spent doing I/Os since the last update of this field(ms)
+# @weight-ticks: weighted time spent doing I/Os since the last update
+#     of this field(ms)
 #
 # Since: 7.1
 ##
@@ -1569,6 +1663,7 @@
 # @guest-get-diskstats:
 #
 # Retrieve information about disk stats.
+#
 # Returns: List of disk stats of guest.
 #
 # Since: 7.1
@@ -1611,8 +1706,8 @@
 #
 # @steal: Stolen time by host (since Linux 2.6.11)
 #
-# @guest: ime spent running a virtual CPU for guest operating systems under
-#         the  control of the Linux kernel (since Linux 2.6.24)
+# @guest: ime spent running a virtual CPU for guest operating systems
+#     under the  control of the Linux kernel (since Linux 2.6.24)
 #
 # @guestnice: Time spent running a niced guest (since Linux 2.6.33)
 #
@@ -1650,6 +1745,7 @@
 # @guest-get-cpustats:
 #
 # Retrieve information about CPU stats.
+#
 # Returns: List of CPU stats of guest.
 #
 # Since: 7.1
Signature · 1 line
2.39.2
Reviewed-by on v1 16/17
#43 lore raw

Re: [PATCH 16/17] qga/qapi-schema: Reformat doc comments to conform to current conventions

Quoted 16 lines · Markus Armbruster

Change

# @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
# do eiusmod tempor incididunt ut labore et dolore magna aliqua.

to

# @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
# do eiusmod tempor incididunt ut labore et dolore magna aliqua.

See recent commit "qapi: Relax doc string @name: description indentation rules" for rationale.

Reflow paragraphs to 70 columns width, and consistently use two spaces to separate sentences.

Quoted 6 lines

To check the generated documentation does not change, I compared the generated HTML before and after this commit with "wdiff -3". Finds no differences. Comparing with diff is not useful, as the reflown paragraphs are visible there.

#44 lore raw

PATCH 17/17 qapi: Reformat doc comments to conform to current conventions

In reply to Markus Armbruster

Change

# @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
# do eiusmod tempor incididunt ut labore et dolore magna aliqua.

to

# @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
# do eiusmod tempor incididunt ut labore et dolore magna aliqua.

See recent commit "qapi: Relax doc string @name: description indentation rules" for rationale.

Reflow paragraphs to 70 columns width, and consistently use two spaces to separate sentences.

To check the generated documentation does not change, I compared the generated HTML before and after this commit with "wdiff -3". Finds no differences. Comparing with diff is not useful, as the reflown paragraphs are visible there.

---
 qapi/acpi.json           |   50 +-
 qapi/audio.json          |   85 +-
 qapi/authz.json          |   29 +-
 qapi/block-core.json     | 2801 ++++++++++++++++++++------------------
 qapi/block-export.json   |  242 ++--
 qapi/block.json          |  214 +--
 qapi/char.json           |  134 +-
 qapi/common.json         |   19 +-
 qapi/compat.json         |   13 +-
 qapi/control.json        |   59 +-
 qapi/crypto.json         |  261 ++--
 qapi/cryptodev.json      |    3 +
 qapi/cxl.json            |   74 +-
 qapi/dump.json           |   78 +-
 qapi/error.json          |    6 +-
 qapi/introspect.json     |   89 +-
 qapi/job.json            |  139 +-
 qapi/machine-target.json |  303 +++--
 qapi/machine.json        |  389 +++---
 qapi/migration.json      | 1117 ++++++++-------
 qapi/misc-target.json    |   67 +-
 qapi/misc.json           |  180 ++-
 qapi/net.json            |  260 ++--
 qapi/pci.json            |   35 +-
 qapi/qapi-schema.json    |   25 +-
 qapi/qdev.json           |   63 +-
 qapi/qom.json            |  404 +++---
 qapi/rdma.json           |    1 -
 qapi/replay.json         |   48 +-
 qapi/rocker.json         |   20 +-
 qapi/run-state.json      |  215 +--
 qapi/sockets.json        |   50 +-
 qapi/stats.json          |   83 +-
 qapi/tpm.json            |   20 +-
 qapi/trace.json          |   34 +-
 qapi/transaction.json    |   87 +-
 qapi/ui.json             |  435 +++---
 qapi/virtio.json         |   84 +-
 qapi/yank.json           |   42 +-
 39 files changed, 4322 insertions(+), 3936 deletions(-)
qapi/acpi.json +25 -25
index d148f6db9f..e0739bd6ae 100644
@@ -14,18 +14,19 @@
 #
 # Specify an ACPI table on the command line to load.
 #
-# At most one of @file and @data can be specified. The list of files specified
-# by any one of them is loaded and concatenated in order. If both are omitted,
-# @data is implied.
+# At most one of @file and @data can be specified.  The list of files
+# specified by any one of them is loaded and concatenated in order.
+# If both are omitted, @data is implied.
 #
-# Other fields / optargs can be used to override fields of the generic ACPI
-# table header; refer to the ACPI specification 5.0, section 5.2.6 System
-# Description Table Header. If a header field is not overridden, then the
-# corresponding value from the concatenated blob is used (in case of @file), or
-# it is filled in with a hard-coded value (in case of @data).
+# Other fields / optargs can be used to override fields of the generic
+# ACPI table header; refer to the ACPI specification 5.0, section
+# 5.2.6 System Description Table Header.  If a header field is not
+# overridden, then the corresponding value from the concatenated blob
+# is used (in case of @file), or it is filled in with a hard-coded
+# value (in case of @data).
 #
-# String fields are copied into the matching ACPI member from lowest address
-# upwards, and silently truncated / NUL-padded to length.
+# String fields are copied into the matching ACPI member from lowest
+# address upwards, and silently truncated / NUL-padded to length.
 #
 # @sig: table signature / identifier (4 bytes)
 #
@@ -38,20 +39,20 @@
 # @oem_rev: OEM-supplied revision number (4 bytes)
 #
 # @asl_compiler_id: identifier of the utility that created the table
-#                   (4 bytes)
+#     (4 bytes)
 #
 # @asl_compiler_rev: revision number of the utility that created the
-#                    table (4 bytes)
+#     table (4 bytes)
 #
-# @file: colon (:) separated list of pathnames to load and
-#        concatenate as table data. The resultant binary blob is expected to
-#        have an ACPI table header. At least one file is required. This field
-#        excludes @data.
+# @file: colon (:) separated list of pathnames to load and concatenate
+#     as table data.  The resultant binary blob is expected to have an
+#     ACPI table header.  At least one file is required.  This field
+#     excludes @data.
 #
-# @data: colon (:) separated list of pathnames to load and
-#        concatenate as table data. The resultant binary blob must not have an
-#        ACPI table header. At least one file is required. This field excludes
-#        @file.
+# @data: colon (:) separated list of pathnames to load and concatenate
+#     as table data.  The resultant binary blob must not have an ACPI
+#     table header.  At least one file is required.  This field
+#     excludes @file.
 #
 # Since: 1.5
 ##
@@ -71,6 +72,7 @@
 # @ACPISlotType:
 #
 # @DIMM: memory slot
+#
 # @CPU: logical CPU slot (since 2.7)
 ##
 { 'enum': 'ACPISlotType', 'data': [ 'DIMM', 'CPU' ] }
@@ -78,9 +80,9 @@
 ##
 # @ACPIOSTInfo:
 #
-# OSPM Status Indication for a device
-# For description of possible values of @source and @status fields
-# see "_OST (OSPM Status Indication)" chapter of ACPI5.0 spec.
+# OSPM Status Indication for a device For description of possible
+# values of @source and @status fields see "_OST (OSPM Status
+# Indication)" chapter of ACPI5.0 spec.
 #
 # @device: device ID associated with slot
 #
@@ -117,7 +119,6 @@
 #                  { "slot": "2", "slot-type": "DIMM", "source": 0, "status": 0},
 #                  { "slot": "3", "slot-type": "DIMM", "source": 0, "status": 0}
 #    ]}
-#
 ##
 { 'command': 'query-acpi-ospm-status', 'returns': ['ACPIOSTInfo'] }
 
@@ -136,7 +137,6 @@
 #      "data": { "info": { "device": "d1", "slot": "0",
 #                          "slot-type": "DIMM", "source": 1, "status": 0 } },
 #      "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
-#
 ##
 { 'event': 'ACPI_DEVICE_OST',
      'data': { 'info': 'ACPIOSTInfo' } }
qapi/audio.json +43 -42

165 lines not on this page · raw message

qapi/authz.json +17 -12
index 51845e37cc..7fc6e3032e 100644
@@ -11,6 +11,7 @@
 # The authorization policy result
 #
 # @deny: deny access
+#
 # @allow: allow access
 #
 # Since: 4.0
@@ -25,6 +26,7 @@
 # The authorization policy match format
 #
 # @exact: an exact string match
+#
 # @glob: string with ? and * shell wildcard support
 #
 # Since: 4.0
@@ -39,7 +41,9 @@
 # A single authorization rule.
 #
 # @match: a string or glob to match against a user identity
+#
 # @policy: the result to return if @match evaluates to true
+#
 # @format: the format of the @match rule (default 'exact')
 #
 # Since: 4.0
@@ -54,7 +58,8 @@
 #
 # Properties for authz-list objects.
 #
-# @policy: Default policy to apply when no rule matches (default: deny)
+# @policy: Default policy to apply when no rule matches (default:
+#     deny)
 #
 # @rules: Authorization rules based on matching user
 #
@@ -69,14 +74,14 @@
 #
 # Properties for authz-listfile objects.
 #
-# @filename: File name to load the configuration from. The file must
-#            contain valid JSON for AuthZListProperties.
+# @filename: File name to load the configuration from.  The file must
+#     contain valid JSON for AuthZListProperties.
 #
-# @refresh: If true, inotify is used to monitor the file, automatically
-#           reloading changes. If an error occurs during reloading, all
-#           authorizations will fail until the file is next successfully
-#           loaded. (default: true if the binary was built with
-#           CONFIG_INOTIFY1, false otherwise)
+# @refresh: If true, inotify is used to monitor the file,
+#     automatically reloading changes.  If an error occurs during
+#     reloading, all authorizations will fail until the file is next
+#     successfully loaded.  (default: true if the binary was built
+#     with CONFIG_INOTIFY1, false otherwise)
 #
 # Since: 4.0
 ##
@@ -101,10 +106,10 @@
 #
 # Properties for authz-simple objects.
 #
-# @identity: Identifies the allowed user. Its format depends on the network
-#            service that authorization object is associated with. For
-#            authorizing based on TLS x509 certificates, the identity must be
-#            the x509 distinguished name.
+# @identity: Identifies the allowed user.  Its format depends on the
+#     network service that authorization object is associated with.
+#     For authorizing based on TLS x509 certificates, the identity
+#     must be the x509 distinguished name.
 #
 # Since: 4.0
 ##
qapi/block-core.json +1469 -1332

2,676 lines not on this page · raw message

qapi/block-export.json +133 -109

242 lines not on this page · raw message

qapi/block.json +114 -100

214 lines not on this page · raw message

qapi/char.json +78 -56

134 lines not on this page · raw message

qapi/common.json +10 -9
index 356db3f670..6fed9cde1a 100644

Lines of this file are not shown. View the raw message.

qapi/compat.json +10 -3
index 39b52872d5..f4c19837eb 100644

Lines of this file are not shown. View the raw message.

qapi/control.json +30 -29

59 lines not on this page · raw message

qapi/crypto.json +157 -104

261 lines not on this page · raw message

qapi/cryptodev.json +3 -0
index cf960ea81f..77f48a9c21 100644

Lines of this file are not shown. View the raw message.

qapi/cxl.json +50 -24

74 lines not on this page · raw message

qapi/dump.json +37 -41

78 lines not on this page · raw message

qapi/error.json +3 -3
index 94a6502de9..135c1e8231 100644

Lines of this file are not shown. View the raw message.

qapi/introspect.json +44 -45

89 lines not on this page · raw message

qapi/job.json +74 -65

139 lines not on this page · raw message

qapi/machine-target.json +160 -143

303 lines not on this page · raw message

qapi/machine.json +204 -185

389 lines not on this page · raw message

qapi/migration.json +551 -566

1,117 lines not on this page · raw message

qapi/misc-target.json +29 -38

67 lines not on this page · raw message

qapi/misc.json +84 -96

180 lines not on this page · raw message

qapi/net.json +126 -134

260 lines not on this page · raw message

qapi/pci.json +18 -17
index ee7c659fec..086c773052 100644

Lines of this file are not shown. View the raw message.

qapi/qapi-schema.json +14 -11
index bb7217da26..31e0b36454 100644

Lines of this file are not shown. View the raw message.

qapi/qdev.json +33 -30

63 lines not on this page · raw message

qapi/qom.json +210 -194

404 lines not on this page · raw message

qapi/rdma.json +0 -1
index 5b6b66afa4..23ebcf7885 100644

Lines of this file are not shown. View the raw message.

qapi/replay.json +22 -26

48 lines not on this page · raw message

qapi/rocker.json +8 -12
index b48e49a89b..31ce0b36f6 100644

Lines of this file are not shown. View the raw message.

qapi/run-state.json +111 -104

215 lines not on this page · raw message

qapi/sockets.json +29 -21

50 lines not on this page · raw message

qapi/stats.json +48 -35

83 lines not on this page · raw message

qapi/tpm.json +12 -8
index eac87d30b2..a754455ca5 100644

Lines of this file are not shown. View the raw message.

qapi/trace.json +19 -15
index f425d10764..6bf0af0946 100644

Lines of this file are not shown. View the raw message.

qapi/transaction.json +50 -37

87 lines not on this page · raw message

qapi/ui.json +247 -188

435 lines not on this page · raw message

qapi/virtio.json +30 -54

84 lines not on this page · raw message

qapi/yank.json +20 -22

42 lines not on this page · raw message

The rest of this diff is not shown. View the raw message.

Signature · 1 line
2.39.2

Part of the diff is not shown here. View the raw message.

Reviewed-by on v1 17/17
#45 lore raw

Re: [PATCH 17/17] qapi: Reformat doc comments to conform to current conventions

Quoted 16 lines · Markus Armbruster

Change

# @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
# do eiusmod tempor incididunt ut labore et dolore magna aliqua.

to

# @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
# do eiusmod tempor incididunt ut labore et dolore magna aliqua.

See recent commit "qapi: Relax doc string @name: description indentation rules" for rationale.

Reflow paragraphs to 70 columns width, and consistently use two spaces to separate sentences.

Quoted 6 lines

To check the generated documentation does not change, I compared the generated HTML before and after this commit with "wdiff -3". Finds no differences. Comparing with diff is not useful, as the reflown paragraphs are visible there.

I am really trusting your run of wdiff -3 O:-)
I haven't read the whole diff.

Acked-by on v1 17/17
#46 lore raw

Re: [PATCH 17/17] qapi: Reformat doc comments to conform to current conventions

In reply to Markus Armbruster
Quoted 16 lines · On Fri, 28 Apr 2023 12:54:29 +0200 Markus Armbruster <[email protected]> wrote:

Change

# @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
# do eiusmod tempor incididunt ut labore et dolore magna aliqua.

to

# @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
# do eiusmod tempor incididunt ut labore et dolore magna aliqua.

See recent commit "qapi: Relax doc string @name: description indentation rules" for rationale.

Reflow paragraphs to 70 columns width, and consistently use two spaces to separate sentences.

Quoted 6 lines

To check the generated documentation does not change, I compared the generated HTML before and after this commit with "wdiff -3". Finds no differences. Comparing with diff is not useful, as the reflown paragraphs are visible there.

Quoted 138 lines
---
 qapi/acpi.json           |   50 +-
 qapi/audio.json          |   85 +-
 qapi/authz.json          |   29 +-
 qapi/block-core.json     | 2801 ++++++++++++++++++++------------------
 qapi/block-export.json   |  242 ++--
 qapi/block.json          |  214 +--
 qapi/char.json           |  134 +-
 qapi/common.json         |   19 +-
 qapi/compat.json         |   13 +-
 qapi/control.json        |   59 +-
 qapi/crypto.json         |  261 ++--
 qapi/cryptodev.json      |    3 +
 qapi/cxl.json            |   74 +-
 qapi/dump.json           |   78 +-
 qapi/error.json          |    6 +-
 qapi/introspect.json     |   89 +-
 qapi/job.json            |  139 +-
 qapi/machine-target.json |  303 +++--
 qapi/machine.json        |  389 +++---
 qapi/migration.json      | 1117 ++++++++-------
 qapi/misc-target.json    |   67 +-
 qapi/misc.json           |  180 ++-
 qapi/net.json            |  260 ++--
 qapi/pci.json            |   35 +-
 qapi/qapi-schema.json    |   25 +-
 qapi/qdev.json           |   63 +-
 qapi/qom.json            |  404 +++---
 qapi/rdma.json           |    1 -
 qapi/replay.json         |   48 +-
 qapi/rocker.json         |   20 +-
 qapi/run-state.json      |  215 +--
 qapi/sockets.json        |   50 +-
 qapi/stats.json          |   83 +-
 qapi/tpm.json            |   20 +-
 qapi/trace.json          |   34 +-
 qapi/transaction.json    |   87 +-
 qapi/ui.json             |  435 +++---
 qapi/virtio.json         |   84 +-
 qapi/yank.json           |   42 +-
 39 files changed, 4322 insertions(+), 3936 deletions(-)

[...]

qapi/yank.json +20 -22
index 1639744ada..87ec7cab96 100644
@@ -9,7 +9,7 @@
 ##
 # @YankInstanceType:
 #
-# An enumeration of yank instance types. See @YankInstance for more
+# An enumeration of yank instance types.  See @YankInstance for more
 # information.
 #
 # Since: 6.0
@@ -20,8 +20,8 @@
 ##
 # @YankInstanceBlockNode:
 #
-# Specifies which block graph node to yank. See @YankInstance for more
-# information.
+# Specifies which block graph node to yank.  See @YankInstance for
+# more information.
 #
 # @node-name: the name of the block graph node
 #
@@ -33,8 +33,8 @@
 ##
 # @YankInstanceChardev:
 #
-# Specifies which character device to yank. See @YankInstance for more
-# information.
+# Specifies which character device to yank.  See @YankInstance for
+# more information.
 #
 # @id: the chardev's ID
 #
@@ -46,21 +46,18 @@
 ##
 # @YankInstance:
 #
-# A yank instance can be yanked with the @yank qmp command to recover from a
-# hanging QEMU.
+# A yank instance can be yanked with the @yank qmp command to recover
+# from a hanging QEMU.
 #
 # Currently implemented yank instances:
 #
-# - nbd block device:
-#   Yanking it will shut down the connection to the nbd server without
-#   attempting to reconnect.
-# - socket chardev:
-#   Yanking it will shut down the connected socket.
-# - migration:
-#   Yanking it will shut down all migration connections. Unlike
-#   @migrate_cancel, it will not notify the migration process, so migration
-#   will go into @failed state, instead of @cancelled state. @yank should be
-#   used to recover from hangs.
+# - nbd block device: Yanking it will shut down the connection to the
+#   nbd server without attempting to reconnect.
+# - socket chardev: Yanking it will shut down the connected socket.
+# - migration: Yanking it will shut down all migration connections.
+#   Unlike @migrate_cancel, it will not notify the migration process,
+#   so migration will go into @failed state, instead of @cancelled
+#   state.  @yank should be used to recover from hangs.
 #
 # Since: 6.0
 ##
@@ -74,13 +71,14 @@
 ##
 # @yank:
 #
-# Try to recover from hanging QEMU by yanking the specified instances. See
-# @YankInstance for more information.
+# Try to recover from hanging QEMU by yanking the specified instances.
+# See @YankInstance for more information.
 #
 # Takes a list of @YankInstance as argument.
 #
-# Returns: - Nothing on success
-#          - @DeviceNotFound error, if any of the YankInstances doesn't exist
+# Returns:
+# - Nothing on success
+# - @DeviceNotFound error, if any of the YankInstances doesn't exist
 #
 # Example:
 #
@@ -101,7 +99,7 @@
 ##
 # @query-yank:
 #
-# Query yank instances. See @YankInstance for more information.
+# Query yank instances.  See @YankInstance for more information.
 #
 # Returns: list of @YankInstance
 #