diff options
| author | Markus Armbruster <armbru@redhat.com> | 2024-02-05 08:47:00 +0100 |
|---|---|---|
| committer | Markus Armbruster <armbru@redhat.com> | 2024-02-12 10:04:31 +0100 |
| commit | 0cec50119f803723f608f6498975799ab35abf52 (patch) | |
| tree | b115456fe01e28a8614b068160043332f36a21bf /tests/qapi-schema | |
| parent | fd62bff901b6c25df4971066b74049548caadc83 (diff) | |
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>
Diffstat (limited to 'tests/qapi-schema')
| -rw-r--r-- | tests/qapi-schema/doc-bad-alternate-member.json | 2 | ||||
| -rw-r--r-- | tests/qapi-schema/doc-good.json | 4 |
2 files changed, 5 insertions, 1 deletions
diff --git a/tests/qapi-schema/doc-bad-alternate-member.json b/tests/qapi-schema/doc-bad-alternate-member.json index fa4143da4c..37593b6698 100644 --- a/tests/qapi-schema/doc-bad-alternate-member.json +++ b/tests/qapi-schema/doc-bad-alternate-member.json @@ -2,6 +2,8 @@ ## # @AorB: +# @a: a +# @b: b # @aa: a # @bb: b ## diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json index 976f9e1aaa..24a84fe6d7 100644 --- a/tests/qapi-schema/doc-good.json +++ b/tests/qapi-schema/doc-good.json @@ -3,7 +3,9 @@ # # Positive QAPI doc comment tests -{ 'pragma': { 'doc-required': true } } +{ 'pragma': { + 'doc-required': true, + 'documentation-exceptions': [ 'Enum', 'Variant1', 'Alternate', 'cmd' ] } } ## # = Section |