3a025d3d | 27-Feb-2024 |
Markus Armbruster <armbru@redhat.com> |
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 ...
|
adb0193b | 16-Feb-2024 |
Markus Armbruster <armbru@redhat.com> |
qapi: Divorce QAPIDoc from QAPIParseError
QAPIDoc stores a reference to QAPIParser just to pass it to QAPIParseError. The resulting error position depends on the state of the parser. It happens to
qapi: Divorce QAPIDoc from QAPIParseError
QAPIDoc stores a reference to QAPIParser just to pass it to QAPIParseError. The resulting error position depends on the state of the parser. It happens to be the current comment line. Servicable, but action at a distance.
The commit before previous moved most uses of QAPIParseError from QAPIDoc to QAPIParser. There are just three left. Convert them to QAPISemError. This involves passing info to a few methods. Then drop the reference to QAPIParser.
The three errors lose the column number. Not really interesting here: it's the comment line's indentation.
Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240216145841.2099240-17-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
show more ...
|
629c5075 | 16-Feb-2024 |
Markus Armbruster <armbru@redhat.com> |
qapi: Reject multiple and empty feature descriptions
The parser recognizes only the first "Features:" line. Any subsequent ones are treated as ordinary text, as visible in test case doc-duplicate-f
qapi: Reject multiple and empty feature descriptions
The parser recognizes only the first "Features:" line. Any subsequent ones are treated as ordinary text, as visible in test case doc-duplicate-features. Recognize "Features:" lines anywhere. A second one is an error.
A 'Features:' line without any features is useless, but not an error. Make it an error. This makes detecting a second "Features:" line easier.
qapi/run-state.json actually has an instance of this since commit fe17522d854 (qapi: Remove deprecated 'singlestep' member of StatusInfo). Clean it up.
Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240216145841.2099240-16-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
show more ...
|
0b82a744 | 16-Feb-2024 |
Markus Armbruster <armbru@redhat.com> |
qapi: Merge adjacent untagged sections
The parser mostly doesn't create adjacent untagged sections, and merging the ones it does create is hardly worth the bother. I'm doing it to avoid behavioral
qapi: Merge adjacent untagged sections
The parser mostly doesn't create adjacent untagged sections, and merging the ones it does create is hardly worth the bother. I'm doing it to avoid behavioral change in the next commit.
Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240216145841.2099240-14-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
show more ...
|
66227e90 | 16-Feb-2024 |
Markus Armbruster <armbru@redhat.com> |
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 ...
|
d23055b8 | 16-Feb-2024 |
Markus Armbruster <armbru@redhat.com> |
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 ...
|
56c64dd6 | 16-Feb-2024 |
Markus Armbruster <armbru@redhat.com> |
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 ...
|
31c54b92 | 16-Feb-2024 |
Markus Armbruster <armbru@redhat.com> |
qapi: Rename QAPIDoc.Section.name to .tag
Since the previous commit, QAPIDoc.Section.name is either None (untagged section) or the section's tag string ('Returns', '@name', ...). Rename it to .tag.
qapi: Rename QAPIDoc.Section.name to .tag
Since the previous commit, QAPIDoc.Section.name is either None (untagged section) or the section's tag string ('Returns', '@name', ...). Rename it to .tag.
Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240216145841.2099240-9-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
show more ...
|
573e2223 | 16-Feb-2024 |
Markus Armbruster <armbru@redhat.com> |
qapi: Improve error message for empty doc sections
Improve the message for an empty tagged section from
empty doc section 'Note'
to
text required after 'Note:'
and the message for an emp
qapi: Improve error message for empty doc sections
Improve the message for an empty tagged section from
empty doc section 'Note'
to
text required after 'Note:'
and the message for an empty argument or feature description from
empty doc section 'foo'
to
text required after '@foo:'
Improve the error position to refer to the beginning of the empty section instead of its end.
Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240216145841.2099240-8-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
show more ...
|
bf00dc19 | 16-Feb-2024 |
Markus Armbruster <armbru@redhat.com> |
qapi: Improve error position for bogus invalid "Returns" section
When something other than a command has a "Returns" section, the error message points to the beginning of the definition comment. Po
qapi: Improve error position for bogus invalid "Returns" section
When something other than a command has a "Returns" section, the error message points to the beginning of the definition comment. Point to the "Returns" section instead.
Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240216145841.2099240-7-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
show more ...
|
15333abe | 16-Feb-2024 |
Markus Armbruster <armbru@redhat.com> |
qapi: Improve error position for bogus argument descriptions
When documented arguments don't exist, the error message points to the beginning of the definition comment. Point to the first bogus arg
qapi: Improve error position for bogus argument descriptions
When documented arguments don't exist, the error message points to the beginning of the definition comment. Point to the first bogus argument description instead.
Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240216145841.2099240-6-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
show more ...
|
0ba2915b | 16-Feb-2024 |
Markus Armbruster <armbru@redhat.com> |
tests/qapi-schema: Cover 'Features:' not followed by descriptions
A 'Features:' line without any features is useless, but not an error now. However, a later commit will make it one, because that ma
tests/qapi-schema: Cover 'Features:' not followed by descriptions
A 'Features:' line without any features is useless, but not an error now. However, a later commit will make it one, because that makes rejecting duplicate 'Features:' easier.
Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240216145841.2099240-4-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
show more ...
|
fc68b9ff | 16-Feb-2024 |
Markus Armbruster <armbru@redhat.com> |
tests/qapi-schema: Cover duplicate 'Features:' line
We don't actually recognize the second 'Features:' line. Instead, we treat it as an untagged section.
If it was followed by feature description,
tests/qapi-schema: Cover duplicate 'Features:' line
We don't actually recognize the second 'Features:' line. Instead, we treat it as an untagged section.
If it was followed by feature description, we'd reject that like "description of '@feat2:' follows a section". Less than clear.
To be improved shortly.
Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240216145841.2099240-3-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
show more ...
|
0cec5011 | 05-Feb-2024 |
Markus Armbruster <armbru@redhat.com> |
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 ...
|
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 ...
|
9b2c6746 | 28-Apr-2023 |
Markus Armbruster <armbru@redhat.com> |
qapi: Fix argument description indentation stripping
When an argument's description starts on the line after the "#arg: " line, indentation is stripped only from the description's first line, as dem
qapi: Fix argument description indentation stripping
When an argument's description starts on the line after the "#arg: " line, indentation is stripped only from the description's first line, as demonstrated by the previous commit. Moreover, subsequent lines with less indentation are not rejected.
Make the first line's indentation the expected indentation for the remainder of the description. This fixes indentation stripping, and also requires at least that much indentation.
Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20230428105429.1687850-12-armbru@redhat.com> Reviewed-by: Juan Quintela <quintela@redhat.com>
show more ...
|
a87a9b4d | 28-Apr-2023 |
Markus Armbruster <armbru@redhat.com> |
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 ...
|