Re: [PATCH 06/15] qapi: Require member documentation (with loophole)

[Daniel P . Berrangé]

On Mon, Feb 05, 2024 at 08:47:00AM +0100, Markus Armbruster wrote:
> 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.

If we want to really annoy people we could print a warning to
stderr during docs generation, for each undocumented field.
The many pages  of warnings would likely trigger a much quicker
series to patches to fix it to eliminate the annoying warnings :-)

> 
> List all the current offenders: 117 commands and types in qapi/, and 9
> in qga/.
> 
> Signed-off-by: Markus Armbruster <armbru@redhat.com>
> ---
>  docs/devel/qapi-code-gen.rst                  |   5 +
>  qapi/pragma.json                              | 119 ++++++++++++++++++
>  qga/qapi-schema.json                          |  13 +-
>  scripts/qapi/parser.py                        |   7 +-
>  scripts/qapi/source.py                        |   2 +
>  .../qapi-schema/doc-bad-alternate-member.json |   2 +
>  tests/qapi-schema/doc-good.json               |   4 +-
>  7 files changed, 149 insertions(+), 3 deletions(-)

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>


With regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|