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 <arm...@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é <berra...@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 :|
