qemu-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Let's close member documentation gaps


From: Markus Armbruster
Subject: Let's close member documentation gaps
Date: Mon, 25 Mar 2024 10:36:47 +0100
User-agent: Gnus/5.13 (Gnus v5.13)

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.




reply via email to

[Prev in Thread] Current Thread [Next in Thread]