Markus Armbruster 08349786c8 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]		2023-05-10 10:00:40 +02:00
..
include
allow-preconfig-test.err
allow-preconfig-test.json
allow-preconfig-test.out
alternate-any.err
alternate-any.json
alternate-any.out
alternate-array.err
alternate-array.json
alternate-array.out
alternate-base.err
alternate-base.json
alternate-base.out
alternate-branch-if-invalid.err
alternate-branch-if-invalid.json
alternate-branch-if-invalid.out
alternate-clash.err
alternate-clash.json
alternate-clash.out
alternate-conflict-bool-string.err
alternate-conflict-bool-string.json
alternate-conflict-bool-string.out
alternate-conflict-dict.err
alternate-conflict-dict.json
alternate-conflict-dict.out
alternate-conflict-enum-bool.err
alternate-conflict-enum-bool.json
alternate-conflict-enum-bool.out
alternate-conflict-enum-int.err
alternate-conflict-enum-int.json
alternate-conflict-enum-int.out
alternate-conflict-lists.err	qapi-schema: test: add a qapi-schema-test for array alternates	2022-04-21 10:11:25 +02:00
alternate-conflict-lists.json	qapi-schema: test: add a qapi-schema-test for array alternates	2022-04-21 10:11:25 +02:00
alternate-conflict-lists.out	qapi-schema: test: add a qapi-schema-test for array alternates	2022-04-21 10:11:25 +02:00
alternate-conflict-num-string.err
alternate-conflict-num-string.json
alternate-conflict-num-string.out
alternate-conflict-string.err
alternate-conflict-string.json
alternate-conflict-string.out
alternate-data-invalid.err
alternate-data-invalid.json
alternate-data-invalid.out
alternate-empty.err
alternate-empty.json
alternate-empty.out
alternate-invalid-dict.err
alternate-invalid-dict.json
alternate-invalid-dict.out
alternate-nested.err
alternate-nested.json
alternate-nested.out
alternate-unknown.err
alternate-unknown.json
alternate-unknown.out
args-alternate.err
args-alternate.json
args-alternate.out
args-any.err
args-any.json
args-any.out
args-array-empty.err
args-array-empty.json
args-array-empty.out
args-array-unknown.err
args-array-unknown.json
args-array-unknown.out
args-bad-boxed.err
args-bad-boxed.json
args-bad-boxed.out
args-boxed-anon.err
args-boxed-anon.json
args-boxed-anon.out
args-boxed-string.err
args-boxed-string.json
args-boxed-string.out
args-if-implicit.err	qapi: Require boxed for conditional command and event arguments	2023-04-24 15:21:39 +02:00
args-if-implicit.json	qapi: Require boxed for conditional command and event arguments	2023-04-24 15:21:39 +02:00
args-if-implicit.out	qapi: Require boxed for conditional command and event arguments	2023-04-24 15:21:39 +02:00
args-if-unboxed.err	qapi: Require boxed for conditional command and event arguments	2023-04-24 15:21:39 +02:00
args-if-unboxed.json	qapi: Require boxed for conditional command and event arguments	2023-04-24 15:21:39 +02:00
args-if-unboxed.out	qapi: Require boxed for conditional command and event arguments	2023-04-24 15:21:39 +02:00
args-int.err
args-int.json
args-int.out
args-invalid.err
args-invalid.json
args-invalid.out
args-member-array-bad.err
args-member-array-bad.json
args-member-array-bad.out
args-member-case.err
args-member-case.json
args-member-case.out
args-member-unknown.err
args-member-unknown.json
args-member-unknown.out
args-union.err
args-union.json
args-union.out
args-unknown.err
args-unknown.json
args-unknown.out
bad-base.err
bad-base.json
bad-base.out
bad-data.err	qapi: Improve error message for unexpected array types	2023-04-24 15:21:39 +02:00
bad-data.json
bad-data.out
bad-ident.err
bad-ident.json
bad-ident.out
bad-if-all.err
bad-if-all.json
bad-if-all.out
bad-if-empty-list.err
bad-if-empty-list.json
bad-if-empty-list.out
bad-if-empty.err
bad-if-empty.json
bad-if-empty.out
bad-if-key.err
bad-if-key.json
bad-if-key.out
bad-if-keys.err
bad-if-keys.json
bad-if-keys.out
bad-if-list.err
bad-if-list.json
bad-if-list.out
bad-if-not.err
bad-if-not.json
bad-if-not.out
bad-if.err
bad-if.json
bad-if.out
bad-type-bool.err
bad-type-bool.json
bad-type-bool.out
bad-type-dict.err
bad-type-dict.json
bad-type-dict.out
bad-type-int.err
bad-type-int.json
bad-type-int.out
base-cycle-direct.err
base-cycle-direct.json
base-cycle-direct.out
base-cycle-indirect.err
base-cycle-indirect.json
base-cycle-indirect.out
command-int.err
command-int.json
command-int.out
comments.err
comments.json
comments.out
doc-bad-alternate-member.err
doc-bad-alternate-member.json
doc-bad-alternate-member.out
doc-bad-boxed-command-arg.err
doc-bad-boxed-command-arg.json
doc-bad-boxed-command-arg.out
doc-bad-command-arg.err
doc-bad-command-arg.json
doc-bad-command-arg.out
doc-bad-enum-member.err
doc-bad-enum-member.json
doc-bad-enum-member.out
doc-bad-event-arg.err
doc-bad-event-arg.json
doc-bad-event-arg.out
doc-bad-feature.err
doc-bad-feature.json
doc-bad-feature.out
doc-bad-indent.err	qapi: Relax doc string @name: description indentation rules	2023-05-10 10:00:40 +02:00
doc-bad-indent.json	qapi: Relax doc string @name: description indentation rules	2023-05-10 10:00:40 +02:00
doc-bad-indent.out
doc-bad-section.err
doc-bad-section.json
doc-bad-section.out
doc-bad-symbol.err
doc-bad-symbol.json
doc-bad-symbol.out
doc-bad-union-member.err
doc-bad-union-member.json
doc-bad-union-member.out
doc-before-include.err
doc-before-include.json
doc-before-include.out
doc-before-pragma.err
doc-before-pragma.json
doc-before-pragma.out
doc-duplicated-arg.err
doc-duplicated-arg.json
doc-duplicated-arg.out
doc-duplicated-return.err
doc-duplicated-return.json
doc-duplicated-return.out
doc-duplicated-since.err
doc-duplicated-since.json
doc-duplicated-since.out
doc-empty-arg.err
doc-empty-arg.json
doc-empty-arg.out
doc-empty-section.err
doc-empty-section.json
doc-empty-section.out
doc-empty-symbol.err
doc-empty-symbol.json
doc-empty-symbol.out
doc-good.err
doc-good.json	qapi: Relax doc string @name: description indentation rules	2023-05-10 10:00:40 +02:00
doc-good.out	qapi: Relax doc string @name: description indentation rules	2023-05-10 10:00:40 +02:00
doc-good.rst
doc-good.txt
doc-interleaved-section.err
doc-interleaved-section.json
doc-interleaved-section.out
doc-invalid-end.err
doc-invalid-end.json
doc-invalid-end.out
doc-invalid-end2.err
doc-invalid-end2.json
doc-invalid-end2.out
doc-invalid-return.err
doc-invalid-return.json
doc-invalid-return.out
doc-invalid-section.err
doc-invalid-section.json
doc-invalid-section.out
doc-invalid-start.err
doc-invalid-start.json
doc-invalid-start.out
doc-missing-colon.err
doc-missing-colon.json
doc-missing-colon.out
doc-missing-expr.err
doc-missing-expr.json
doc-missing-expr.out
doc-missing-space.err
doc-missing-space.json
doc-missing-space.out
doc-missing.err
doc-missing.json
doc-missing.out
doc-no-symbol.err
doc-no-symbol.json
doc-no-symbol.out
doc-undoc-feature.err
doc-undoc-feature.json
doc-undoc-feature.out
double-type.err
double-type.json
double-type.out
duplicate-key.err
duplicate-key.json
duplicate-key.out
empty.err
empty.json
empty.out
enum-bad-member.err
enum-bad-member.json
enum-bad-member.out
enum-bad-name.err
enum-bad-name.json
enum-bad-name.out
enum-bad-prefix.err
enum-bad-prefix.json
enum-bad-prefix.out
enum-clash-member.err
enum-clash-member.json
enum-clash-member.out
enum-dict-member-unknown.err
enum-dict-member-unknown.json
enum-dict-member-unknown.out
enum-dict-no-name.err
enum-dict-no-name.json
enum-dict-no-name.out
enum-if-invalid.err
enum-if-invalid.json
enum-if-invalid.out
enum-int-member.err
enum-int-member.json
enum-int-member.out
enum-member-case.err
enum-member-case.json
enum-member-case.out
enum-missing-data.err
enum-missing-data.json
enum-missing-data.out
enum-wrong-data.err
enum-wrong-data.json
enum-wrong-data.out
escape-outside-string.err
event-args-if-unboxed.err	qapi: Require boxed for conditional command and event arguments	2023-04-24 15:21:39 +02:00
event-args-if-unboxed.json	qapi: Require boxed for conditional command and event arguments	2023-04-24 15:21:39 +02:00
event-args-if-unboxed.out	qapi: Require boxed for conditional command and event arguments	2023-04-24 15:21:39 +02:00
event-boxed-empty.err
event-boxed-empty.json
event-boxed-empty.out
event-case.err
event-case.json
event-case.out
event-member-invalid-dict.err
event-member-invalid-dict.json
event-member-invalid-dict.out
event-nest-struct.err	qapi: Fix error message when type name or array is expected	2023-04-24 15:21:39 +02:00
event-nest-struct.json
event-nest-struct.out
features-bad-type.err
features-bad-type.json
features-bad-type.out
features-deprecated-type.err
features-deprecated-type.json
features-deprecated-type.out
features-duplicate-name.err
features-duplicate-name.json
features-duplicate-name.out
features-if-invalid.err
features-if-invalid.json
features-if-invalid.out
features-missing-name.err
features-missing-name.json
features-missing-name.out
features-name-bad-type.err
features-name-bad-type.json
features-name-bad-type.out
features-no-list.err
features-no-list.json
features-no-list.out
features-unknown-key.err
features-unknown-key.json
features-unknown-key.out
funny-char.err
funny-char.json
funny-char.out
funny-word.err
funny-word.json
funny-word.out
ident-with-escape.err
ident-with-escape.json
ident-with-escape.out
include-before-err.err
include-before-err.json
include-before-err.out
include-cycle-b.json
include-cycle-c.json
include-cycle.err
include-cycle.json
include-cycle.out
include-extra-junk.err
include-extra-junk.json
include-extra-junk.out
include-nested-err.err
include-nested-err.json
include-nested-err.out
include-no-file.err
include-no-file.json
include-no-file.out
include-non-file.err
include-non-file.json
include-non-file.out
include-repetition-sub.json
include-repetition.err
include-repetition.json
include-repetition.out
include-self-cycle.err
include-self-cycle.json
include-self-cycle.out
include-simple-sub.json
include-simple.err
include-simple.json
include-simple.out
indented-expr.err
indented-expr.json
indented-expr.out
leading-comma-list.err
leading-comma-list.json
leading-comma-list.out
leading-comma-object.err
leading-comma-object.json
leading-comma-object.out
meson.build	qapi: allow unions to contain further unions	2023-04-26 07:52:45 +02:00
missing-array-rsqb.err
missing-array-rsqb.json
missing-array-rsqb.out
missing-colon.err
missing-colon.json
missing-colon.out
missing-comma-list.err
missing-comma-list.json
missing-comma-list.out
missing-comma-object.err
missing-comma-object.json
missing-comma-object.out
missing-object-member-element.err
missing-object-member-element.json
missing-object-member-element.out
missing-schema.err
missing-schema.out
missing-type.err
missing-type.json
missing-type.out
nested-struct-data-invalid-dict.err
nested-struct-data-invalid-dict.json
nested-struct-data-invalid-dict.out
nested-struct-data.err	qapi: Fix error message when type name or array is expected	2023-04-24 15:21:39 +02:00
nested-struct-data.json
nested-struct-data.out
non-objects.err
non-objects.json
non-objects.out
oob-coroutine.err
oob-coroutine.json
oob-coroutine.out
oob-test.err
oob-test.json
oob-test.out
pragma-extra-junk.err
pragma-extra-junk.json
pragma-extra-junk.out
pragma-non-dict.err
pragma-non-dict.json
pragma-non-dict.out
pragma-unknown.err
pragma-unknown.json
pragma-unknown.out
pragma-value-not-bool.err
pragma-value-not-bool.json
pragma-value-not-bool.out
pragma-value-not-list-of-str.err
pragma-value-not-list-of-str.json
pragma-value-not-list-of-str.out
pragma-value-not-list.err
pragma-value-not-list.json
pragma-value-not-list.out
qapi-schema-test.err
qapi-schema-test.json	qapi: allow unions to contain further unions	2023-04-26 07:52:45 +02:00
qapi-schema-test.out	qapi: allow unions to contain further unions	2023-04-26 07:52:45 +02:00
quoted-structural-chars.err
quoted-structural-chars.json
quoted-structural-chars.out
redefined-command.err
redefined-command.json
redefined-command.out
redefined-event.err
redefined-event.json
redefined-event.out
redefined-predefined.err
redefined-predefined.json
redefined-predefined.out
redefined-type.err
redefined-type.json
redefined-type.out
reserved-command-q.err
reserved-command-q.json
reserved-command-q.out
reserved-enum-q.err
reserved-enum-q.json
reserved-enum-q.out
reserved-member-has.err
reserved-member-has.json
reserved-member-has.out
reserved-member-q.err
reserved-member-q.json
reserved-member-q.out
reserved-member-u.err
reserved-member-u.json
reserved-member-u.out
reserved-member-underscore.err
reserved-member-underscore.json
reserved-member-underscore.out
reserved-type-list.err
reserved-type-list.json
reserved-type-list.out
returns-alternate.err
returns-alternate.json
returns-alternate.out
returns-array-bad.err
returns-array-bad.json
returns-array-bad.out
returns-bad-type.err
returns-bad-type.json
returns-bad-type.out
returns-dict.err	qapi: Fix error message when type name or array is expected	2023-04-24 15:21:39 +02:00
returns-dict.json
returns-dict.out
returns-unknown.err
returns-unknown.json
returns-unknown.out
string-code-point-31.err
string-code-point-31.json
string-code-point-31.out
string-code-point-127.err
string-code-point-127.json
string-code-point-127.out
struct-base-clash-deep.err
struct-base-clash-deep.json
struct-base-clash-deep.out
struct-base-clash.err
struct-base-clash.json
struct-base-clash.out
struct-data-invalid.err
struct-data-invalid.json
struct-data-invalid.out
struct-data-typename.err	qapi: Fix to reject 'data': 'mumble' in struct	2023-04-24 15:21:39 +02:00
struct-data-typename.json	qapi: Fix to reject 'data': 'mumble' in struct	2023-04-24 15:21:39 +02:00
struct-data-typename.out	qapi: Fix to reject 'data': 'mumble' in struct	2023-04-24 15:21:39 +02:00
struct-member-if-invalid.err
struct-member-if-invalid.json
struct-member-if-invalid.out
struct-member-invalid-dict.err
struct-member-invalid-dict.json
struct-member-invalid-dict.out
struct-member-invalid.err	qapi: Fix error message when type name or array is expected	2023-04-24 15:21:39 +02:00
struct-member-invalid.json
struct-member-invalid.out
struct-member-name-clash.err
struct-member-name-clash.json
struct-member-name-clash.out
sub-sub-module.json
test-qapi.py	qapi: support updating expected test output via make	2023-04-25 15:23:06 +02:00
trailing-comma-list.err
trailing-comma-list.json
trailing-comma-list.out
trailing-comma-object.err
trailing-comma-object.json
trailing-comma-object.out
type-bypass-bad-gen.err
type-bypass-bad-gen.json
type-bypass-bad-gen.out
type-case.err
type-case.json
type-case.out
unclosed-list.err
unclosed-list.json
unclosed-list.out
unclosed-object.err
unclosed-object.json
unclosed-object.out
unclosed-string.err
unclosed-string.json
unclosed-string.out
union-array-branch.err	qapi: Improve error message for unexpected array types	2023-04-24 15:21:39 +02:00
union-array-branch.json
union-array-branch.out
union-bad-base.err
union-bad-base.json
union-bad-base.out
union-bad-discriminator.err
union-bad-discriminator.json
union-bad-discriminator.out
union-base-any.err
union-base-any.json
union-base-any.out
union-base-empty.err
union-base-empty.json
union-base-empty.out
union-base-no-discriminator.err
union-base-no-discriminator.json
union-base-no-discriminator.out
union-base-union.err
union-base-union.json
union-base-union.out
union-branch-if-invalid.err
union-branch-if-invalid.json
union-branch-if-invalid.out
union-branch-invalid-dict.err
union-branch-invalid-dict.json
union-branch-invalid-dict.out
union-clash-member.err
union-clash-member.json
union-clash-member.out
union-discriminator-bad-name.err
union-discriminator-bad-name.json
union-discriminator-bad-name.out
union-empty.err
union-empty.json
union-empty.out
union-inline-invalid-dict.err
union-inline-invalid-dict.json
union-inline-invalid-dict.out
union-int-branch.err
union-int-branch.json
union-int-branch.out
union-invalid-base.err
union-invalid-base.json
union-invalid-base.out
union-invalid-branch-key.err
union-invalid-branch-key.json
union-invalid-branch-key.out
union-invalid-data.err
union-invalid-data.json
union-invalid-data.out
union-invalid-discriminator.err	tests/qapi-schema: Improve union discriminator coverage	2023-04-24 15:21:39 +02:00
union-invalid-discriminator.json	tests/qapi-schema: Improve union discriminator coverage	2023-04-24 15:21:39 +02:00
union-invalid-discriminator.out
union-invalid-if-discriminator.err
union-invalid-if-discriminator.json
union-invalid-if-discriminator.out
union-invalid-union-subfield.err	qapi: allow unions to contain further unions	2023-04-26 07:52:45 +02:00
union-invalid-union-subfield.json	qapi: allow unions to contain further unions	2023-04-26 07:52:45 +02:00
union-invalid-union-subfield.out	qapi: allow unions to contain further unions	2023-04-26 07:52:45 +02:00
union-invalid-union-subtype.err	qapi: allow unions to contain further unions	2023-04-26 07:52:45 +02:00
union-invalid-union-subtype.json	qapi: allow unions to contain further unions	2023-04-26 07:52:45 +02:00
union-invalid-union-subtype.out	qapi: allow unions to contain further unions	2023-04-26 07:52:45 +02:00
union-no-base.err
union-no-base.json
union-no-base.out
union-optional-discriminator.err
union-optional-discriminator.json
union-optional-discriminator.out
union-string-discriminator.err
union-string-discriminator.json
union-string-discriminator.out
union-unknown.err
union-unknown.json
union-unknown.out
unknown-escape.err
unknown-escape.json
unknown-escape.out
unknown-expr-key.err
unknown-expr-key.json
unknown-expr-key.out