qapi: New documentation section tag "Errors"

We use section "Returns" for documenting both success and error
response of commands.

I intend to generate better command success response documentation

qapi: New documentation section tag "Errors"

We use section "Returns" for documenting both success and error
response of commands.

I intend to generate better command success response documentation.
Easier when "Returns" documents just he success response.

Create new section tag "Errors". The next two commits will move error
response documentation from "Returns" sections to "Errors" sections.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240227113921.236097-4-armbru@redhat.com>

show more ...

qapi: New documentation section tag "Errors"

We use section "Returns" for documenting both success and error
response of commands.

I intend to generate better command success response documentation

qapi: New documentation section tag "Errors"

We use section "Returns" for documenting both success and error
response of commands.

I intend to generate better command success response documentation.
Easier when "Returns" documents just he success response.

Create new section tag "Errors". The next two commits will move error
response documentation from "Returns" sections to "Errors" sections.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240227113921.236097-4-armbru@redhat.com>

show more ...

qapi: Recognize section tags and 'Features:' only after blank line

Putting a blank line before section tags and 'Features:' is good,
existing practice. Enforce it.

Signed-off-by: Markus Armbruster

qapi: Recognize section tags and 'Features:' only after blank line

Putting a blank line before section tags and 'Features:' is good,
existing practice. Enforce it.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240216145841.2099240-12-armbru@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>

show more ...

qapi: Require descriptions and tagged sections to be indented

By convention, we indent the second and subsequent lines of
descriptions and tagged sections, except for examples.

Turn this into a har

qapi: Require descriptions and tagged sections to be indented

By convention, we indent the second and subsequent lines of
descriptions and tagged sections, except for examples.

Turn this into a hard rule, and apply it to examples, too.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240216145841.2099240-11-armbru@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
[Straightforward conflicts in qapi/migration.json resolved]

show more ...

qapi: Reject section heading in the middle of a doc comment

docs/devel/qapi-code-gen.txt claims "A heading line must be the first
line of the documentation comment block" since commit
55ec69f8b16 (d

qapi: Reject section heading in the middle of a doc comment

docs/devel/qapi-code-gen.txt claims "A heading line must be the first
line of the documentation comment block" since commit
55ec69f8b16 (docs/devel/qapi-code-gen.txt: Update to new rST backend
conventions). Not true, we have code to make it work anywhere in a
free-form doc comment: commit dcdc07a97cb (qapi: Make section headings
start a new doc comment block).

Make it true, for simplicity's sake.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240216145841.2099240-10-armbru@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>

show more ...

qapi: Require member documentation (with loophole)

The QAPI generator forces you to document your stuff. Except for
command arguments, event data, and members of enum and object types:
these the ge

qapi: Require member documentation (with loophole)

The QAPI generator forces you to document your stuff. Except for
command arguments, event data, and members of enum and object types:
these the generator silently "documents" as "Not documented".

We can't require proper documentation there without first fixing all
the offenders. We've always had too many offenders to pull that off.
Right now, we have more than 500. Worse, we seem to fix old ones no
faster than we add new ones: in the past year, we fixed 22 ones, but
added 26 new ones.

To help arrest the backsliding, make missing documentation an error
unless the command, type, or event is in listed in new pragma
documentation-exceptions.

List all the current offenders: 117 commands and types in qapi/, and 9
in qga/.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240205074709.3613229-7-armbru@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>

show more ...

qapi: Indent tagged doc comment sections properly

docs/devel/qapi-code-gen demands that the "second and subsequent lines
of sections other than "Example"/"Examples" should be indented".
Commit a937b

qapi: Indent tagged doc comment sections properly

docs/devel/qapi-code-gen demands that the "second and subsequent lines
of sections other than "Example"/"Examples" should be indented".
Commit a937b6aa739q (qapi: Reformat doc comments to conform to current
conventions) missed a few instances, and messed up a few others.
Clean that up.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240205074709.3613229-5-armbru@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>

show more ...

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 ...

tests/qapi-schema/doc-good: Improve argument description tests

Improve the comments to better describe what they test.

Cover argument description starting on a new line indented. This
style isn't

tests/qapi-schema/doc-good: Improve argument description tests

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.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20230428105429.1687850-11-armbru@redhat.com>
Reviewed-by: Juan Quintela <quintela@redhat.com>

show more ...

tests/qapi-schema/doc-good: Improve a comment

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

tests/qapi-schema/doc-good: Improve a comment

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".

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20230428105429.1687850-10-armbru@redhat.com>
Reviewed-by: Juan Quintela <quintela@redhat.com>

show more ...

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 ...

tests/qapi-schema/doc-good: Improve argument description tests

Improve the comments to better describe what they test.

Cover argument description starting on a new line indented. This
style isn't

tests/qapi-schema/doc-good: Improve argument description tests

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.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20230428105429.1687850-11-armbru@redhat.com>
Reviewed-by: Juan Quintela <quintela@redhat.com>

show more ...

tests/qapi-schema/doc-good: Improve a comment

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

tests/qapi-schema/doc-good: Improve a comment

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".

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20230428105429.1687850-10-armbru@redhat.com>
Reviewed-by: Juan Quintela <quintela@redhat.com>

show more ...

qapi: Add feature flags to enum members

This is quite similar to commit 84ab008687 "qapi: Add feature flags to
struct members", only for enums instead of structs.

Special feature flag 'deprecated'

qapi: Add feature flags to enum members

This is quite similar to commit 84ab008687 "qapi: Add feature flags to
struct members", only for enums instead of structs.

Special feature flag 'deprecated' is silently ignored there. This is
okay only because it will be implemented shortly.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Message-Id: <20211025042405.3762351-3-armbru@redhat.com>
Reviewed-by: John Snow <jsnow@redhat.com>

show more ...

qapi: Add spaces after symbol declaration for consistency

Several QGA definitions omit a blank line after the symbol
declaration. This works OK currently, but it's the only place where we
do this. A

qapi: Add spaces after symbol declaration for consistency

Several QGA definitions omit a blank line after the symbol
declaration. This works OK currently, but it's the only place where we
do this. Adjust it for consistency.

Future commits may wind up enforcing this formatting.

Signed-off-by: John Snow <jsnow@redhat.com>

Message-Id: <20210930205716.1148693-5-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>

show more ...

tests/qapi-schema: Purge simple unions from tests

Drop tests that are specifically about simple unions:

* SugaredUnion in doc-good: flat unions are covered by @Object.

* union-branch-case and unio

tests/qapi-schema: Purge simple unions from tests

Drop tests that are specifically about simple unions:

* SugaredUnion in doc-good: flat unions are covered by @Object.

* union-branch-case and union-clash-branches: branch naming for flat
unions is enforced for the tag enum instead, which is covered by
enum-member-case and enum-clash-member.

* union-empty: empty flat unions are covered by flat-union-empty.

Rewrite the remainder to use flat unions: args-union, bad-base,
flat-union-base-union, union-branch-invalid-dict, union-unknown.

Except drop union-optional-branch. because converting this one is not
worth the trouble; we don't explicitly check names beginning with '*'
in other places, either.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Message-Id: <20210917143134.412106-21-armbru@redhat.com>

show more ...

qapi: Tidy up unusual line breaks

Break lines between members instead of within members.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat

qapi: Tidy up unusual line breaks

Break lines between members instead of within members.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Message-Id: <20210917143134.412106-2-armbru@redhat.com>

show more ...

tests/qapi-schema: Demonstrate broken C code for 'if'

The C code generated for 'if' conditionals is incorrectly
parenthesized. For instance,

'if': { 'not': { 'any': [ { 'not': 'TEST_IF_EVT' },

tests/qapi-schema: Demonstrate broken C code for 'if'

The C code generated for 'if' conditionals is incorrectly
parenthesized. For instance,

'if': { 'not': { 'any': [ { 'not': 'TEST_IF_EVT' },
{ 'not': 'TEST_IF_STRUCT' } ] } } }

generates

#if !(!defined(TEST_IF_EVT)) || (!defined(TEST_IF_STRUCT))

This is wrong. Correct would be:

#if !(!defined(TEST_IF_EVT) || !defined(TEST_IF_STRUCT))

Cover the issue in qapi-schema-test.json. This generates bad #if in
tests/test-qapi-events.h and other files.

Add a similar condition to doc-good.json. The generated documentation
is fine.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20210831123809.1107782-5-armbru@redhat.com>
Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>

show more ...

qapi: make 'if' condition strings simple identifiers

Change the 'if' condition strings to be C-agnostic. It will accept
'[A-Z][A-Z0-9_]*' identifiers. This allows to express configuration
conditions

qapi: make 'if' condition strings simple identifiers

Change the 'if' condition strings to be C-agnostic. It will accept
'[A-Z][A-Z0-9_]*' identifiers. This allows to express configuration
conditions in other languages (Rust or Python for ex) or other more
suitable forms.

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com>
Tested-by: John Snow <jsnow@redhat.com>
Message-Id: <20210804083105.97531-11-marcandre.lureau@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Rebased with semantic conflict in redefined-event.json]
Signed-off-by: Markus Armbruster <armbru@redhat.com>

show more ...

qapi: add 'not' condition operation

For the sake of completeness, introduce the 'not' condition.

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Message-Id: <20210804083105.97531-10-

qapi: add 'not' condition operation

For the sake of completeness, introduce the 'not' condition.

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Message-Id: <20210804083105.97531-10-marcandre.lureau@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Long line broken in tests/qapi-schema/qapi-schema-test.json]
Signed-off-by: Markus Armbruster <armbru@redhat.com>

show more ...

qapi: add 'any' condition

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Message-Id: <20210804083105.97531-8-marcandre.lureau@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redha

qapi: add 'any' condition

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Message-Id: <20210804083105.97531-8-marcandre.lureau@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>

show more ...

qapi: replace if condition list with dict {'all': [...]}

Replace the simple list sugar form with a recursive structure that will
accept other operators in the following commits (all, any or not).

S

qapi: replace if condition list with dict {'all': [...]}

Replace the simple list sugar form with a recursive structure that will
accept other operators in the following commits (all, any or not).

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Message-Id: <20210804083105.97531-7-marcandre.lureau@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Accidental code motion undone. Degenerate :forms: comment dropped.
Helper _check_if() moved. Error messages tweaked. ui.json updated.
Accidental changes to qapi-schema-test.json dropped.]
Signed-off-by: Markus Armbruster <armbru@redhat.com>

show more ...

qapi: Enforce event naming rules

Event names should be ALL_CAPS with words separated by underscore.
Enforce this. The only offenders are in tests/. Fix them. Existing
test event-case covers the n

qapi: Enforce event naming rules

Event names should be ALL_CAPS with words separated by underscore.
Enforce this. The only offenders are in tests/. Fix them. Existing
test event-case covers the new error.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20210323094025.3569441-14-armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>

show more ...

tests/qapi-schema: Convert doc-good.json to rST-style strong/emphasis

doc-good.json currently uses the old *strong* and _emphasis_ markup.
As part of the conversion to rST this needs to switch to **

tests/qapi-schema: Convert doc-good.json to rST-style strong/emphasis

doc-good.json currently uses the old *strong* and _emphasis_ markup.
As part of the conversion to rST this needs to switch to **strong**
and *emphasis*, because rST uses underscores as part of its markup
of hyperlinks and will otherwise warn about the syntax error.

In commit a660eed482063b we fixed up the in-tree uses of the
old markup:
1) _this_ was replaced with *this*
2) the only in-tree use of *this* was left alone (turning
a 'strong' into an 'emphasis')
(and so currently in-tree nothing is using either new-style
**strong** or old-style _emphasis_).

Update doc-good.json in a similar way:
1) replace _this_ with *this*
2) remove the usage of old-style *this*

(This slightly reduces the coverage for the old Texinfo generator,
which is about to go away, but is fine for the new rST generator
because that does not need to handle strong/emphasis itself because
it is simply passing the entire text as raw rST to Sphinx.)

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Message-Id: <20200925162316.21205-13-peter.maydell@linaro.org>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>

show more ...

tests/qapi/doc-good.json: Prepare for qapi-doc Sphinx extension

doc-good.json tests doc comment parser corner cases. We're about to
largely replace it by a Sphinx extension, which will have differe

tests/qapi/doc-good.json: Prepare for qapi-doc Sphinx extension

doc-good.json tests doc comment parser corner cases. We're about to
largely replace it by a Sphinx extension, which will have different
corner cases. Tweak the test so it passes both with the old parser
and the Sphinx extension, by making it match the more restrictive
rST syntax:

* in a single list the bullet types must all match
* lists must have leading and following blank lines
* the rules on when and where indentation matters differ
* the '|' example syntax is going to go away entirely, so stop
testing it

This will avoid the tests spuriously breaking when we tighten up the
parser code in the following commits.

Reviewed-by: Richard Henderson <richard.henderson@linaro.org>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Message-Id: <20200925162316.21205-4-peter.maydell@linaro.org>
Signed-off-by: Markus Armbruster <armbru@redhat.com>

show more ...