0cec50119f
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. List all the current offenders: 117 commands and types in qapi/, and 9 in qga/. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240205074709.3613229-7-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
188 lines
6.5 KiB
Python
188 lines
6.5 KiB
Python
# -*- Mode: Python -*-
|
|
# vim: filetype=python
|
|
|
|
{ 'pragma': { 'doc-required': true } }
|
|
|
|
# Entries in these lists are allowed to violate the QAPI rules (for
|
|
# historical reasons); think twice before you add to them!
|
|
{ 'pragma': {
|
|
# Command names containing '_'
|
|
'command-name-exceptions': [
|
|
'add_client',
|
|
'block_resize',
|
|
'block_set_io_throttle',
|
|
'client_migrate_info',
|
|
'device_add',
|
|
'device_del',
|
|
'expire_password',
|
|
'migrate_cancel',
|
|
'netdev_add',
|
|
'netdev_del',
|
|
'qmp_capabilities',
|
|
'set_link',
|
|
'set_password',
|
|
'system_powerdown',
|
|
'system_reset',
|
|
'system_wakeup' ],
|
|
# Commands allowed to return a non-dictionary
|
|
'command-returns-exceptions': [
|
|
'human-monitor-command',
|
|
'qom-get',
|
|
'query-tpm-models',
|
|
'query-tpm-types',
|
|
'ringbuf-read' ],
|
|
# Types, commands, and events with undocumented members / arguments:
|
|
'documentation-exceptions': [
|
|
'AbortWrapper',
|
|
'AudiodevDriver',
|
|
'BlkdebugEvent',
|
|
'BlockDirtyBitmapAddWrapper',
|
|
'BlockDirtyBitmapMergeWrapper',
|
|
'BlockDirtyBitmapWrapper',
|
|
'BlockExportOptions',
|
|
'BlockStatsSpecific',
|
|
'BlockdevBackupWrapper',
|
|
'BlockdevDriver',
|
|
'BlockdevQcow2Encryption',
|
|
'BlockdevQcow2EncryptionFormat',
|
|
'BlockdevQcowEncryption',
|
|
'BlockdevSnapshotInternalWrapper',
|
|
'BlockdevSnapshotSyncWrapper',
|
|
'BlockdevSnapshotWrapper',
|
|
'BlockdevVmdkAdapterType',
|
|
'ChardevBackend',
|
|
'ChardevBackendKind',
|
|
'ChardevCommonWrapper',
|
|
'ChardevDBusWrapper',
|
|
'ChardevFileWrapper',
|
|
'ChardevHostdevWrapper',
|
|
'ChardevMuxWrapper',
|
|
'ChardevQemuVDAgentWrapper',
|
|
'ChardevRingbufWrapper',
|
|
'ChardevSocketWrapper',
|
|
'ChardevSpiceChannelWrapper',
|
|
'ChardevSpicePortWrapper',
|
|
'ChardevStdioWrapper',
|
|
'ChardevUdpWrapper',
|
|
'ChardevVCWrapper',
|
|
'CpuS390Entitlement',
|
|
'CpuS390Polarization',
|
|
'CpuS390State',
|
|
'CxlCorErrorType',
|
|
'DisplayProtocol',
|
|
'DriveBackupWrapper',
|
|
'DummyBlockCoreForceArrays',
|
|
'DummyForceArrays',
|
|
'DummyVirtioForceArrays',
|
|
'DumpGuestMemoryCapability',
|
|
'GrabToggleKeys',
|
|
'GuestPanicInformationHyperV',
|
|
'HotKeyMod',
|
|
'HvBalloonDeviceInfoWrapper',
|
|
'ImageInfoSpecific',
|
|
'ImageInfoSpecificFileWrapper',
|
|
'ImageInfoSpecificKind',
|
|
'ImageInfoSpecificLUKSWrapper',
|
|
'ImageInfoSpecificQCow2Wrapper',
|
|
'ImageInfoSpecificRbdWrapper',
|
|
'ImageInfoSpecificVmdkWrapper',
|
|
'InetSocketAddressWrapper',
|
|
'InputAxis',
|
|
'InputBtnEventWrapper',
|
|
'InputButton',
|
|
'InputKeyEventWrapper',
|
|
'InputMoveEventWrapper',
|
|
'InputMultiTouchEvent',
|
|
'InputMultiTouchEventWrapper',
|
|
'InputMultiTouchType',
|
|
'IntWrapper',
|
|
'IscsiHeaderDigest',
|
|
'IscsiTransport',
|
|
'JSONType',
|
|
'KeyValue',
|
|
'KeyValueKind',
|
|
'MemoryDeviceInfo',
|
|
'MemoryDeviceInfoKind',
|
|
'MigrateSetParameters',
|
|
'MigrationAddress',
|
|
'NetClientDriver',
|
|
'NumaOptions',
|
|
'ObjectType',
|
|
'PCDIMMDeviceInfoWrapper',
|
|
'PciMemoryRegion',
|
|
'QCryptoAkCipherKeyType',
|
|
'QCryptoAkCipherOptions',
|
|
'QCryptodevBackendServiceType',
|
|
'QKeyCode',
|
|
'QKeyCodeWrapper',
|
|
'Qcow2OverlapCheckFlags',
|
|
'RbdAuthMode',
|
|
'RbdEncryptionCreateOptions',
|
|
'RbdImageEncryptionFormat',
|
|
'SgxEPCDeviceInfoWrapper',
|
|
'SocketAddressLegacy',
|
|
'SshHostKeyCheck',
|
|
'StatsFilter',
|
|
'StatsValue',
|
|
'String',
|
|
'StringWrapper',
|
|
'SysEmuTarget',
|
|
'TPMEmulatorOptionsWrapper',
|
|
'TPMPassthroughOptionsWrapper',
|
|
'ThrottleGroupProperties',
|
|
'TransactionAction',
|
|
'UnixSocketAddressWrapper',
|
|
'VirtioMEMDeviceInfoWrapper',
|
|
'VirtioPMEMDeviceInfoWrapper',
|
|
'VncPrimaryAuth',
|
|
'VncVencryptSubAuth',
|
|
'VsockSocketAddressWrapper',
|
|
'X86CPURegister32',
|
|
'XDbgBlockGraph',
|
|
'YankInstance',
|
|
'YankInstanceType',
|
|
'blockdev-reopen',
|
|
'query-cpu-model-baseline',
|
|
'query-cpu-model-comparison',
|
|
'query-cpu-model-expansion',
|
|
'query-rocker',
|
|
'query-rocker-ports',
|
|
'query-stats-schemas',
|
|
'watchdog-set-action',
|
|
'yank' ],
|
|
# Externally visible types whose member names may use uppercase
|
|
'member-name-exceptions': [ # visible in:
|
|
'ACPISlotType', # query-acpi-ospm-status
|
|
'AcpiTableOptions', # -acpitable
|
|
'BlkdebugEvent', # blockdev-add, -blockdev
|
|
'BlkdebugSetStateOptions', # blockdev-add, -blockdev
|
|
'BlockDeviceInfo', # query-block
|
|
'BlockDeviceStats', # query-blockstats
|
|
'BlockDeviceTimedStats', # query-blockstats
|
|
'BlockIOThrottle', # block_set_io_throttle
|
|
'BlockInfo', # query-block
|
|
'BlockdevAioOptions', # blockdev-add, -blockdev
|
|
'BlockdevDriver', # blockdev-add, query-blockstats, ...
|
|
'BlockdevVmdkAdapterType', # blockdev-create (to match VMDK spec)
|
|
'BlockdevVmdkSubformat', # blockdev-create (to match VMDK spec)
|
|
'ColoCompareProperties', # object_add, -object
|
|
'FilterMirrorProperties', # object_add, -object
|
|
'FilterRedirectorProperties', # object_add, -object
|
|
'FilterRewriterProperties', # object_add, -object
|
|
'InputLinuxProperties', # object_add, -object
|
|
'NetdevTapOptions', # netdev_add, query-netdev, -netdev
|
|
'ObjectType', # object-add, -object
|
|
'PCIELinkSpeed', # internal only
|
|
'PciBusInfo', # query-pci
|
|
'PciDeviceInfo', # query-pci
|
|
'PciMemoryRegion', # query-pci
|
|
'QKeyCode', # send-key, input-sent-event
|
|
'QapiErrorClass', # QMP error replies
|
|
'SshHostKeyCheckMode', # blockdev-add, -blockdev
|
|
'SysEmuTarget', # query-cpu-fast, query-target
|
|
'UuidInfo', # query-uuid
|
|
'VncClientInfo', # query-vnc, query-vnc-servers, ...
|
|
'X86CPURegister32' # qom-get of x86 CPU properties
|
|
# feature-words, filtered-features
|
|
] } }
|