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

[Markus Armbruster <armbru@redhat.com>]

Daniel P. Berrangé <berrange@redhat.com> writes:

> 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 :-)

Heh.

Let's give not annoying people that much a try.  Can always escalate
later :)

[...]