[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-devel] [PATCH v2 for-2.9 02/47] qapi: Make doc comments option
From: |
Eric Blake |
Subject: |
Re: [Qemu-devel] [PATCH v2 for-2.9 02/47] qapi: Make doc comments optional where we don't need them |
Date: |
Wed, 15 Mar 2017 09:25:38 -0500 |
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:45.0) Gecko/20100101 Thunderbird/45.8.0 |
On 03/15/2017 07:56 AM, Markus Armbruster wrote:
> Since we added the documentation generator in commit 3313b61, doc
> comments are mandatory. That's a very good idea for a schema that
> needs to be documented, but has proven to be annoying for testing.
>
> Make doc comments optional again, but add a new directive
>
> { 'pragma': { 'doc-required': true } }
>
> to let a QAPI schema require them.
>
> Add test cases for the new pragma directive. While there, plug a
> minor hole in includ directive test coverage.
s/includ/include/
>
> Require documentation in the schemas we actually want documented:
> qapi-schema.json and qga/qapi-schema.json.
>
> We could probably make qapi2texi.py cope with incomplete
> documentation, but for now, simply make it refuse to run unless the
> schema has 'doc-required': true.
>
> Signed-off-by: Markus Armbruster <address@hidden>
> ---
> +=== Pragma directives ===
> +
> +Usage: { 'pragma': DICT }
> +
> +The pragma directive lets you control optional generator behavior.
> +The dictionary's entries are pragma names and values.
> +
> +Pragma's scope is currently the complete schema. Setting it to
You can do:
{ 'pragma': { 'doc-required': true } }
{ 'pragma': { 'whitelist': [...] } }
what you can't do is:
{ 'pragma': { 'doc-required': true } }
{ 'pragma': { 'doc-required': false } }
Maybe s/Setting it/Setting a given pragma name/
> +different values in parts of the schema doesn't work.
> +
> +Pragma 'doc-required' takes a boolean value. If true, documentation
> +is required. Default is false.
> +
> +
The new tests are nice; thanks.
Reviewed-by: Eric Blake <address@hidden>
--
Eric Blake eblake redhat com +1-919-301-3266
Libvirt virtualization library http://libvirt.org
signature.asc
Description: OpenPGP digital signature
- [Qemu-devel] [PATCH v2 for-2.9 16/47] qapi2texi: Convert to QAPISchemaVisitor, (continued)
- [Qemu-devel] [PATCH v2 for-2.9 16/47] qapi2texi: Convert to QAPISchemaVisitor, Markus Armbruster, 2017/03/15
- [Qemu-devel] [PATCH v2 for-2.9 32/47] qapi: Move detection of doc / expression name mismatch, Markus Armbruster, 2017/03/15
- [Qemu-devel] [PATCH v2 for-2.9 22/47] qapi2texi: Explain enum value undocumentedness more clearly, Markus Armbruster, 2017/03/15
- [Qemu-devel] [PATCH v2 for-2.9 34/47] qapi: Move empty doc section checking to doc parser, Markus Armbruster, 2017/03/15
- [Qemu-devel] [PATCH v2 for-2.9 14/47] qapi: Prepare for requiring more complete documentation, Markus Armbruster, 2017/03/15
- [Qemu-devel] [PATCH v2 for-2.9 42/47] qapi: enum_types is a list used like a dict, make it one, Markus Armbruster, 2017/03/15
- [Qemu-devel] [PATCH v2 for-2.9 07/47] qapi: Clean up build of generated documentation, Markus Armbruster, 2017/03/15
- [Qemu-devel] [PATCH v2 for-2.9 20/47] qapi2texi: Plainer enum value and member name formatting, Markus Armbruster, 2017/03/15
- [Qemu-devel] [PATCH v2 for-2.9 11/47] qapi: Avoid unwanted blank lines in QAPIDoc, Markus Armbruster, 2017/03/15
- [Qemu-devel] [PATCH v2 for-2.9 02/47] qapi: Make doc comments optional where we don't need them, Markus Armbruster, 2017/03/15
- Re: [Qemu-devel] [PATCH v2 for-2.9 02/47] qapi: Make doc comments optional where we don't need them,
Eric Blake <=
- [Qemu-devel] [PATCH v2 for-2.9 29/47] qapi2texi: Use category "Object" for all object types, Markus Armbruster, 2017/03/15
- [Qemu-devel] [PATCH v2 for-2.9 25/47] qapi2texi: Include member type in generated documentation, Markus Armbruster, 2017/03/15
- [Qemu-devel] [PATCH v2 for-2.9 18/47] qapi: Use raw strings for regular expressions consistently, Markus Armbruster, 2017/03/15
- [Qemu-devel] [PATCH v2 for-2.9 26/47] qapi2texi: Generate reference to base type members, Markus Armbruster, 2017/03/15
- [Qemu-devel] [PATCH v2 for-2.9 28/47] qapi2texi: Generate descriptions for simple union tags, Markus Armbruster, 2017/03/15
- [Qemu-devel] [PATCH v2 for-2.9 27/47] qapi2texi: Generate documentation for variant members, Markus Armbruster, 2017/03/15
- [Qemu-devel] [PATCH v2 for-2.9 21/47] qapi2texi: Present the table of members more clearly, Markus Armbruster, 2017/03/15
- [Qemu-devel] [PATCH v2 for-2.9 24/47] qapi2texi: Implement boxed argument documentation, Markus Armbruster, 2017/03/15