fridtjof/qemu-cr16
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
qemu-cr16/tests/qapi-schema
History
John Snow 3c5f6114d9 qapi: remove "Example" doc section 
Fully eliminate the "Example" sections in QAPI doc blocks now that they
have all been converted to arbitrary rST syntax using the
".. qmp-example::" directive. Update tests to match.

Migrating to the new syntax
---------------------------

The old "Example:" or "Examples:" section syntax is now caught as an
error, but "Example::" is stil permitted as explicit rST syntax for an
un-lexed, generic preformatted text block.

('Example' is not special in this case, any sentence that ends with "::"
will start an indented code block in rST.)

Arbitrary rST for Examples is now possible, but it's strongly
recommended that documentation authors use the ".. qmp-example::"
directive for consistent visual formatting in rendered HTML docs. The
":title:" directive option may be used to add extra information into the
title bar for the example. The ":annotated:" option can be used to write
arbitrary rST instead, with nested "::" blocks applying QMP formatting
where desired.

Other choices available are ".. code-block:: QMP" which will not create
an "Example:" box, or the short-form "::" code-block syntax which will
not apply QMP highlighting when used outside of the qmp-example
directive.

Why?
----

This patch has several benefits:

1. Example sections can now be written more arbitrarily, mixing
   explanatory paragraphs and code blocks however desired.

2. Example sections can now use fully arbitrary rST.

3. All code blocks are now lexed and validated as QMP; increasing
   usability of the docs and ensuring validity of example snippets.

   (To some extent - This patch only gaurantees it lexes correctly, not
   that it's valid under the JSON or QMP grammars. It will catch most
   small mistakes, however.)

4. Each qmp-example can be titled or annotated independently without
   bypassing the QMP lexer/validator.

   (i.e. code blocks are now for *code* only, so we don't have to
   sacrifice exposition for having lexically valid examples.)

NOTE: As with the "Notes" conversion (d461c27973), this patch (and the
      three preceding) may change the rendering order for Examples in
      the current generator. The forthcoming qapidoc rewrite will fix
      this by always generating documentation in source order.

Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20240717021312.606116-10-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
2024-07-17 10:20:54 +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 tests/: spelling fixes 2023-09-08 13:08:52 +03:00
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 qapi: Improve error position for bogus argument descriptions 2024-02-26 10:43:56 +01:00
doc-bad-alternate-member.json qapi: Require member documentation (with loophole) 2024-02-12 10:04:31 +01:00
doc-bad-alternate-member.out
doc-bad-boxed-command-arg.err qapi: Improve error position for bogus argument descriptions 2024-02-26 10:43:56 +01:00
doc-bad-boxed-command-arg.json
doc-bad-boxed-command-arg.out
doc-bad-command-arg.err qapi: Improve error position for bogus argument descriptions 2024-02-26 10:43:56 +01:00
doc-bad-command-arg.json
doc-bad-command-arg.out
doc-bad-enum-member.err qapi: Improve error position for bogus argument descriptions 2024-02-26 10:43:56 +01:00
doc-bad-enum-member.json
doc-bad-enum-member.out
doc-bad-event-arg.err qapi: Improve error position for bogus argument descriptions 2024-02-26 10:43:56 +01:00
doc-bad-event-arg.json
doc-bad-event-arg.out
doc-bad-feature.err qapi: Improve error position for bogus argument descriptions 2024-02-26 10:43:56 +01:00
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 qapi: Improve error position for bogus argument descriptions 2024-02-26 10:43:56 +01:00
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-duplicate-features.err qapi: Reject multiple and empty feature descriptions 2024-02-26 10:43:56 +01:00
doc-duplicate-features.json tests/qapi-schema: Cover duplicate 'Features:' line 2024-02-26 10:43:56 +01:00
doc-duplicate-features.out qapi: Reject multiple and empty feature descriptions 2024-02-26 10:43:56 +01:00
doc-duplicated-arg.err qapi: Divorce QAPIDoc from QAPIParseError 2024-02-26 10:43:56 +01:00
doc-duplicated-arg.json
doc-duplicated-arg.out
doc-duplicated-return.err qapi: Divorce QAPIDoc from QAPIParseError 2024-02-26 10:43:56 +01:00
doc-duplicated-return.json qapi: Recognize section tags and 'Features:' only after blank line 2024-02-26 10:43:56 +01:00
doc-duplicated-return.out
doc-duplicated-since.err qapi: Divorce QAPIDoc from QAPIParseError 2024-02-26 10:43:56 +01:00
doc-duplicated-since.json qapi: Recognize section tags and 'Features:' only after blank line 2024-02-26 10:43:56 +01:00
doc-duplicated-since.out
doc-empty-arg.err qapi: Divorce QAPIDoc from QAPIParseError 2024-02-26 10:43:56 +01:00
doc-empty-arg.json
doc-empty-arg.out
doc-empty-features.err qapi: Reject multiple and empty feature descriptions 2024-02-26 10:43:56 +01:00
doc-empty-features.json tests/qapi-schema: Cover 'Features:' not followed by descriptions 2024-02-26 10:43:56 +01:00
doc-empty-features.out qapi: Reject multiple and empty feature descriptions 2024-02-26 10:43:56 +01:00
doc-empty-section.err qapi: convert "Note" sections to plain rST 2024-07-06 08:58:24 +02:00
doc-empty-section.json qapi: convert "Note" sections to plain rST 2024-07-06 08:58:24 +02:00
doc-empty-section.out
doc-empty-symbol.err
doc-empty-symbol.json
doc-empty-symbol.out
doc-good.err
doc-good.json qapi: remove "Example" doc section 2024-07-17 10:20:54 +02:00
doc-good.out qapi: remove "Example" doc section 2024-07-17 10:20:54 +02:00
doc-good.rst
doc-good.txt qapi: remove "Example" doc section 2024-07-17 10:20:54 +02:00
doc-interleaved-section.err qapi: Improve error message for description following section 2023-05-22 10:03:26 +02:00
doc-interleaved-section.json qapi: convert "Note" sections to plain rST 2024-07-06 08:58:24 +02:00
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 qapi: Slightly clearer error message for invalid "Returns" section 2024-03-04 07:12:40 +01:00
doc-invalid-return.json qapi: Recognize section tags and 'Features:' only after blank line 2024-02-26 10:43:56 +01:00
doc-invalid-return.out
doc-invalid-return2.err qapi: Reject "Returns" section when command doesn't return anything 2024-03-04 07:12:40 +01:00
doc-invalid-return2.json qapi: Reject "Returns" section when command doesn't return anything 2024-03-04 07:12:40 +01:00
doc-invalid-return2.out qapi: Reject "Returns" section when command doesn't return anything 2024-03-04 07:12:40 +01:00
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-non-first-section.err qapi: Reject section heading in the middle of a doc comment 2024-02-26 10:43:56 +01:00
doc-non-first-section.json qapi: Reject section heading in the middle of a doc comment 2024-02-26 10:43:56 +01:00
doc-non-first-section.out qapi: Reject section heading in the middle of a doc comment 2024-02-26 10:43:56 +01:00
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: Reject "Returns" section when command doesn't return anything 2024-03-04 07:12:40 +01: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: Rename visitor parameter @variants to @alternatives 2024-05-06 12:38:27 +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