* Let's close member documentation gaps
@ 2024-03-25 9:36 Markus Armbruster
2024-03-25 14:13 ` David Hildenbrand
2024-03-26 8:27 ` Markus Armbruster
0 siblings, 2 replies; 5+ messages in thread
From: Markus Armbruster @ 2024-03-25 9:36 UTC (permalink / raw
To: qemu-devel
Cc: Vladimir Sementsov-Ogievskiy, Kevin Wolf, Hanna Czenczek,
David Hildenbrand, Michael S. Tsirkin, Marcel Apfelbaum,
Jiri Pirko, Paolo Bonzini, Marc-André Lureau
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.
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: Let's close member documentation gaps
2024-03-25 9:36 Let's close member documentation gaps Markus Armbruster
@ 2024-03-25 14:13 ` David Hildenbrand
2024-03-25 14:14 ` David Hildenbrand
2024-03-26 8:27 ` Markus Armbruster
1 sibling, 1 reply; 5+ messages in thread
From: David Hildenbrand @ 2024-03-25 14:13 UTC (permalink / raw
To: Markus Armbruster, qemu-devel
Cc: Vladimir Sementsov-Ogievskiy, Kevin Wolf, Hanna Czenczek,
Michael S. Tsirkin, Marcel Apfelbaum, Jiri Pirko, Paolo Bonzini,
Marc-André Lureau
On 25.03.24 10:36, Markus Armbruster wrote:
> 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.
>
What would be the right step to make sure I am resolving these "hidden"
issues, and that the QAPI generator would be happy with my changes?
--
Cheers,
David / dhildenb
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: Let's close member documentation gaps
2024-03-25 14:13 ` David Hildenbrand
@ 2024-03-25 14:14 ` David Hildenbrand
2024-03-25 14:36 ` Markus Armbruster
0 siblings, 1 reply; 5+ messages in thread
From: David Hildenbrand @ 2024-03-25 14:14 UTC (permalink / raw
To: Markus Armbruster, qemu-devel
Cc: Vladimir Sementsov-Ogievskiy, Kevin Wolf, Hanna Czenczek,
Michael S. Tsirkin, Marcel Apfelbaum, Jiri Pirko, Paolo Bonzini,
Marc-André Lureau
On 25.03.24 15:13, David Hildenbrand wrote:
> On 25.03.24 10:36, Markus Armbruster wrote:
>> 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.
>>
>
> What would be the right step to make sure I am resolving these "hidden"
> issues, and that the QAPI generator would be happy with my changes?
Ah, I assume simply removing the offender from "qapi/pragma.json" and
then compiling.
--
Cheers,
David / dhildenb
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: Let's close member documentation gaps
2024-03-25 14:14 ` David Hildenbrand
@ 2024-03-25 14:36 ` Markus Armbruster
0 siblings, 0 replies; 5+ messages in thread
From: Markus Armbruster @ 2024-03-25 14:36 UTC (permalink / raw
To: David Hildenbrand
Cc: qemu-devel, Vladimir Sementsov-Ogievskiy, Kevin Wolf,
Hanna Czenczek, Michael S. Tsirkin, Marcel Apfelbaum, Jiri Pirko,
Paolo Bonzini, Marc-André Lureau
David Hildenbrand <david@redhat.com> writes:
> On 25.03.24 15:13, David Hildenbrand wrote:
>> On 25.03.24 10:36, Markus Armbruster wrote:
>>> 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.
>>>
>> What would be the right step to make sure I am resolving these "hidden"
>> issues, and that the QAPI generator would be happy with my changes?
>
> Ah, I assume simply removing the offender from "qapi/pragma.json" and then compiling.
Correct!
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: Let's close member documentation gaps
2024-03-25 9:36 Let's close member documentation gaps Markus Armbruster
2024-03-25 14:13 ` David Hildenbrand
@ 2024-03-26 8:27 ` Markus Armbruster
1 sibling, 0 replies; 5+ messages in thread
From: Markus Armbruster @ 2024-03-26 8:27 UTC (permalink / raw
To: qemu-devel; +Cc: Jason Wang
Markus Armbruster <armbru@redhat.com> writes:
> 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/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.
I decided not to.
String is used for NetdevUserOptions members @dnssearch, @hostfwd, and
@guestfwd. NetdevUserOptions are the type-specific arguments of
netdev-add with type "user".
@dnssearch is documented tolerably well, although there's less
information than for the CLI equivalent in qemu-options.hx.
@hostfwd is not: the string format is not documented at all. It's its
own mini-language. The CLI equivalent in qemu-options.hx documents it.
Of course, encoding information in strings like that is bad practice in
QMP. Probably not worth fixing now.
Same for @guestfwd.
These documentation deficiencies are more serious than the "Not
documented" for String. Only fixing the latter seems not worthwhile.
Jason, thoughts?
[...]
^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2024-03-26 8:28 UTC | newest]
Thread overview: 5+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2024-03-25 9:36 Let's close member documentation gaps Markus Armbruster
2024-03-25 14:13 ` David Hildenbrand
2024-03-25 14:14 ` David Hildenbrand
2024-03-25 14:36 ` Markus Armbruster
2024-03-26 8:27 ` Markus Armbruster
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.