If you're cc'ed, I have a bit of doc work for you. Search for your
name to find it.
The QAPI generator forces you to document your stuff. Except for
commands, events, enum and object types listed in pragma
documentation-exceptions, the generator silently defaults missing
documentation to "Not documented". Right now, we're using this loophole
some 500 times.
Most of the offenders are enumeration values. Their meaning is perhaps
easier to guess than the meaning of command arguments, member data, and
object type members. Ignoring enumerations leaves 62 offenders. Let's
examine them.
= qapi/block-core.json
* DummyBlockCoreForceArrays
Not actually part of the external interface, ignore.
* Qcow2OverlapCheckFlags
If the user needs to know what the flags do, then the flags need to be
documented. Else, they should not be part of the stable interface.
Vladimir, if the former, please fix. If the latter, please mark them
unstable.
* ThrottleGroupProperties
The unstable properties you're not supposed to use are undocumented.
Tolerable, I guess.
* XDbgBlockGraph
Only user is x-debug-query-block-graph, which is for debugging.
Tolerable, I guess.
* blockdev-reopen
The documentation refers to the argument ("the given set of options"),
but since it lacks a formal @option: section, the generator concludes
it doesn't, and supplies its "Not documented" description.
Embarrassing. Kevin or Hanna, please fix.
= qapi/machine-target.json
* query-cpu-model-baseline
* query-cpu-model-comparison
The documentation refers to the arguments ("two CPU models"), but
since it lacks formal @modela: and @modelb: sections, the generator
concludes it doesn't, and supplies its "Not documented" description.
Embarrassing. David, please fix.
* query-cpu-model-expansion
Likewise, only the references to the arguments are even more vague.
David, please fix.
= qapi/machine.json
* DummyForceArrays
Not actually part of the external interface, ignore.
= qapi/net.json
* String
Lack of the @str: section produces an embarrassing "Not documented" in
the generated documentation. I can post a patch to make it less
embarrassing. I doubt we can make it actually good, as generic
wrapper types like this one have meaning only in the context they are
used. Therefore, their meaning can be usefully explained only at
their uses, not their definition.
= qapi/pci.json
* PciMemoryRegion
Michael or Marcel, please document @address.
= qapi/rocker.json
* query-rocker
* query-rocker-ports
Jiri, please document the argument.
= qapi/run-state.json
* GuestPanicInformationHyperV
Paolo, please document the members.
* watchdog-set-action
Paolo, please document the argument, or ask me to do it for you.
= qapi/stats.json
* StatsFilter
Paolo, please document @providers.
* StatsValue
Paolo, please document @boolean.
* query-stats-schemas
Paolo, please document the argument.
= qapi/transaction.json
* AbortWrapper
* BlockDirtyBitmapAddWrapper
* BlockDirtyBitmapMergeWrapper
* BlockDirtyBitmapWrapper
* BlockdevBackupWrapper
* BlockdevSnapshotInternalWrapper
* BlockdevSnapshotSyncWrapper
* BlockdevSnapshotWrapper
* DriveBackupWrapper
Kevin or Hana, please document the member.
Similar wrapper types elsewhere simply steal from the wrapped type's
description. Trouble is the ones wrapped here lack a description.
= qapi/ui.json
* InputMultiTouchEvent
Marc-André, please document @type.
= qapi/virtio.json
* DummyVirtioForceArrays
Not actually part of the external interface, ignore.
