[00/15] 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.

PATCH 01-05 are bonus fixes & cleanups.

PATCH 06 makes missing documentation an error unless the command,
type, or event is in listed in new pragma documentation-exceptions.

PATCH 07-09 improve the "QEMU Guest Agent Protocol Reference" manual:
they document eight members and arguments, reducing the number of
offending commands and types from nine to one.  The 25 members of type
GuestNVMeSmart are left undocumented.

PATCH 10-15 improve reduce the "QEMU QMP Reference Manual" manual, but
only a bit: they document 54 members and arguments, reducing number of
offending commands and types from 117 to 65.  467 members and
arguments are left undocumented.  A few of them are not actually used
in QMP, and documenting them is not worthwhile; they should be elided
from the manual instead.  Example: DummyForceArrays.

Remaining definitions with undocumented members:

    FILE
        DEFINITION #MISSING
    ----------------------------------------------
    qga/qapi-schema.json
        GuestNVMeSmart 25
    qapi/audio.json
	AudiodevDriver 12
    qapi/block-core.json
	BlkdebugEvent 43
	BlockdevDriver 39
	BlockdevQcow2EncryptionFormat 1
	BlockdevVmdkAdapterType 4
	DummyBlockCoreForceArrays 1
	ImageInfoSpecificKind 2
	IscsiHeaderDigest 4
	IscsiTransport 2
	Qcow2OverlapCheckFlags 8
	RbdAuthMode 2
	RbdImageEncryptionFormat 2
	ThrottleGroupProperties 19
	XDbgBlockGraph 2
	blockdev-reopen 1
    qapi/char.json
	ChardevBackendKind 6
    qapi/common.json
	GrabToggleKeys 6
    qapi/crypto.json
	QCryptoAkCipherKeyType 2
    qapi/cryptodev.json
	QCryptodevBackendServiceType 5
    qapi/cxl.json
	CxlCorErrorType 1
    qapi/introspect.json
	JSONType 8
    qapi/machine-common.json
	CpuS390Entitlement 4
    qapi/machine-target.json
	CpuS390Polarization 2
	query-cpu-model-baseline 2
	query-cpu-model-comparison 2
	query-cpu-model-expansion 2
    qapi/machine.json
	CpuS390State 5
	DummyForceArrays 1
	MemoryDeviceInfoKind 1
	SysEmuTarget 29
	X86CPURegister32 8
    qapi/migration.json
	MigrateSetParameters 1
    qapi/net.json
	NetClientDriver 10
	String 1
    qapi/pci.json
	PciMemoryRegion 1
    qapi/qom.json
	ObjectType 45
    qapi/rocker.json
	query-rocker 1
	query-rocker-ports 1
    qapi/run-state.json
	GuestPanicInformationHyperV 5
	watchdog-set-action 1
    qapi/stats.json
	StatsFilter 1
	StatsValue 1
	query-stats-schemas 1
    qapi/transaction.json
	AbortWrapper 1
	BlockDirtyBitmapAddWrapper 1
	BlockDirtyBitmapMergeWrapper 1
	BlockDirtyBitmapWrapper 1
	BlockdevBackupWrapper 1
	BlockdevSnapshotInternalWrapper 1
	BlockdevSnapshotSyncWrapper 1
	BlockdevSnapshotWrapper 1
	DriveBackupWrapper 1
    qapi/ui.json
	DisplayProtocol 2
	HotKeyMod 3
	InputAxis 2
	InputButton 7
	InputMultiTouchEvent 1
	InputMultiTouchType 5
	KeyValueKind 2
	QKeyCode 119
	VncPrimaryAuth 9
	VncVencryptSubAuth 9
    qapi/virtio.json
	DummyVirtioForceArrays 1
    qapi/yank.json
	YankInstanceType 3

Markus Armbruster (15):
  docs/devel/qapi-code-gen: Normalize version refs x.y.0 to just x.y
  docs/devel/qapi-code-gen: Tweak doc comment whitespace
  qapi/block-core: Fix BlockLatencyHistogramInfo doc markup
  qapi: Indent tagged doc comment sections properly
  sphinx/qapidoc: Drop code to generate doc for simple union tag
  qapi: Require member documentation (with loophole)
  qga/qapi-schema: Clean up documentation of guest-set-memory-blocks
  qga/qapi-schema: Clean up documentation of guest-set-vcpus
  qga/qapi-schema: Plug trivial documentation holes
  qapi/yank: Clean up documentaion of yank
  qapi/dump: Clean up documentation of DumpGuestMemoryCapability
  qapi: Plug trivial documentation holes around former simple unions
  qapi: Improve documentation of file descriptor socket addresses
  qapi: Move @String out of common.json to discourage reuse
  qapi: Add missing union tag documentation

 docs/devel/qapi-code-gen.rst                  | 14 ++--
 docs/sphinx/qapidoc.py                        |  6 --
 qapi/block-core.json                          | 26 ++++++-
 qapi/block-export.json                        |  2 +
 qapi/char.json                                | 28 ++++++++
 qapi/common.json                              | 11 ---
 qapi/crypto.json                              |  2 +
 qapi/dump.json                                |  2 +-
 qapi/machine.json                             | 14 ++++
 qapi/migration.json                           | 48 ++++++-------
 qapi/misc.json                                | 12 ++--
 qapi/net.json                                 | 12 +++-
 qapi/pragma.json                              | 67 +++++++++++++++++++
 qapi/qdev.json                                | 12 ++--
 qapi/sockets.json                             | 48 +++++++++----
 qapi/stats.json                               |  2 +
 qapi/tpm.json                                 |  4 ++
 qapi/transaction.json                         |  2 +
 qapi/ui.json                                  | 14 ++++
 qapi/yank.json                                |  4 +-
 qga/qapi-schema.json                          | 58 ++++++++++------
 include/hw/virtio/vhost-vsock-common.h        |  1 +
 include/net/filter.h                          |  2 +-
 chardev/char-socket.c                         |  2 +-
 util/qemu-sockets.c                           |  3 +-
 scripts/qapi/parser.py                        |  7 +-
 scripts/qapi/source.py                        |  2 +
 .../qapi-schema/doc-bad-alternate-member.json |  2 +
 tests/qapi-schema/doc-good.json               | 14 ++--
 tests/qapi-schema/doc-good.out                |  2 +-
 30 files changed, 317 insertions(+), 106 deletions(-)

On Mon, Feb 05, 2024 at 08:46:54AM +0100, Markus Armbruster wrote:
>     qapi/migration.json
> 	MigrateSetParameters 1

It's tls-authz.  I'll send a patch for this one.

Thanks,