Markus Armbruster <arm...@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? [...]
