Re: Let's close member documentation gaps

[Markus Armbruster]

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?

[...]