| Message ID | 20230428105429.1687850-1-armbru@redhat.com (mailing list archive) |
|---|---|
| Headers | show |
| Series | qapi: Reformat doc comments | expand |
Forgot to mention: it's based on my "[PULL 00/17] QAPI patches patches for 2023-04-28". Apologies!
Markus Armbruster <armbru@redhat.com> 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. > > 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. > > Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Juan Quintela <quintela@redhat.com> I am really trusting your run of wdiff -3 O:-) I haven't read the whole diff.
On Fri, 28 Apr 2023 12:54:29 +0200 Markus Armbruster <armbru@redhat.com> 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. > > 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. > > Signed-off-by: Markus Armbruster <armbru@redhat.com> Acked-by: Lukas Straub <lukasstraub2@web.de> > --- > 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(-) > > [...] > > diff --git a/qapi/yank.json b/qapi/yank.json > index 1639744ada..87ec7cab96 100644 > --- a/qapi/yank.json > +++ b/qapi/yank.json > @@ -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 > # --
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: <87v8irv7zq.fsf@pond.sub.org> 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(-)