#
08349786 |
| 28-Apr-2023 |
Markus Armbruster <armbru@redhat.com> |
qapi: Relax doc string @name: description indentation rules
The QAPI schema doc comment language provides special syntax for command and event arguments, struct and union members, alternate branches
qapi: Relax doc string @name: description indentation rules
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.
Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20230428105429.1687850-14-armbru@redhat.com> Reviewed-by: Juan Quintela <quintela@redhat.com> [Work around lack of walrus operator in Python 3.7 and older]
show more ...
|
#
b23317ee |
| 01-Oct-2020 |
Peter Maydell <peter.maydell@linaro.org> |
Merge remote-tracking branch 'remotes/kraxel/tags/microvm-20200930-pull-request' into staging microvm: add pcie support. # gpg: Signature made Wed 30 Sep 2020 18:48:41 BST # gpg
Merge remote-tracking branch 'remotes/kraxel/tags/microvm-20200930-pull-request' into staging microvm: add pcie support. # gpg: Signature made Wed 30 Sep 2020 18:48:41 BST # gpg: using RSA key 4CB6D8EED3E87138 # gpg: Good signature from "Gerd Hoffmann (work) <kraxel@redhat.com>" [full] # gpg: aka "Gerd Hoffmann <gerd@kraxel.org>" [full] # gpg: aka "Gerd Hoffmann (private) <kraxel@gmail.com>" [full] # Primary key fingerprint: A032 8CFF B93A 17A7 9901 FE7D 4CB6 D8EE D3E8 7138 * remotes/kraxel/tags/microvm-20200930-pull-request: tests/acpi: update expected data files acpi/gpex: no reason to use a method for _CRS tests/acpi: add microvm pcie test tests/acpi: factor out common microvm test setup tests/acpi: add empty tests/data/acpi/microvm/DSDT.pcie file tests/acpi: allow updates for expected data files microvm/pcie: add 64bit mmio window microvm: add pcie support microvm: add irq table arm: use acpi_dsdt_add_gpex acpi: add acpi_dsdt_add_gpex move MemMapEntry Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
show more ...
|
#
cbba3dc6 |
| 30-Sep-2020 |
Peter Maydell <peter.maydell@linaro.org> |
Merge remote-tracking branch 'remotes/mst/tags/for_upstream' into staging acpi: unit test This just adds a unit test for previously merged functionality. A bit unusual, but we h
Merge remote-tracking branch 'remotes/mst/tags/for_upstream' into staging acpi: unit test This just adds a unit test for previously merged functionality. A bit unusual, but we have a contribitor under a deadline, let's be nice and merge the unit test right away - does no harm. Hopefully this won't be a beginning of a trend ... Signed-off-by: Michael S. Tsirkin <mst@redhat.com> # gpg: Signature made Wed 30 Sep 2020 09:13:13 BST # gpg: using RSA key 5D09FD0871C8F85B94CA8A0D281F0DB8D28D5469 # gpg: issuer "mst@redhat.com" # gpg: Good signature from "Michael S. Tsirkin <mst@kernel.org>" [full] # gpg: aka "Michael S. Tsirkin <mst@redhat.com>" [full] # Primary key fingerprint: 0270 606B 6F3C DF3D 0B17 0970 C350 3912 AFBE 8E67 # Subkey fingerprint: 5D09 FD08 71C8 F85B 94CA 8A0D 281F 0DB8 D28D 5469 * remotes/mst/tags/for_upstream: tests/acpi: add DSDT.hpbrroot DSDT table blob to test global i440fx hotplug tests/acpi: unit test exercising global pci hotplug off for i440fx Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
show more ...
|
#
a69a6d4b |
| 25-Sep-2020 |
Peter Maydell <peter.maydell@linaro.org> |
scripts/qapi/parser.py: improve doc comment indent handling Make the handling of indentation in doc comments more sophisticated, so that when we see a section like: Notes: some
scripts/qapi/parser.py: improve doc comment indent handling Make the handling of indentation in doc comments more sophisticated, so that when we see a section like: Notes: some text some more text indented line 3 we save it for the doc-comment processing code as: some text some more text indented line 3 and when we see a section with the heading on its own line: Notes: some text some more text indented text we also accept that and save it in the same form. If we detect that the comment document text is not indented as much as we expect it to be, we throw a parse error. (We don't complain about over-indented sections, because for rST this can be legitimate markup.) The golden reference for the doc comment text is updated to remove the two 'wrong' indents; these now form a test case that we correctly stripped leading whitespace from an indented multi-line argument definition. We update the documentation in docs/devel/qapi-code-gen.txt to describe the new indentation rules. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Message-Id: <20200925162316.21205-6-peter.maydell@linaro.org> Reviewed-by: Markus Armbruster <armbru@redhat.com> [Whitespace between sentences tweaked] Signed-off-by: Markus Armbruster <armbru@redhat.com>
show more ...
|