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(-)
--
2.43.0
