Re: [Qemu-devel] Should the "props" be documented for QMP `object-add`?

["Daniel P. Berrangé" <berrange@redhat.com>]

On Wed, Jan 09, 2019 at 09:51:13AM +0100, Kashyap Chamarthy wrote:
> I notice that the following QMP command:
> 
>     {
>       "execute":"object-add",
>       "arguments":{
>         "qom-type":"tls-creds-x509",
>         "id":"objlibvirt_migrate_tls0",
>         "props":{
>           "dir":"/etc/pki/qemu",
>           "endpoint":"server",
>           "verify-peer":true
>         }
>       }
>     }
> 
> ... is the same as its command-line equivalent:
> 
>     -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server,verify-peer=yes
> 
> That said, in qapi/misc.json "@object-add" doesn't document any of the
> "props".  Is it on purpose?  Maybe because it is a 1:1 mapping of the
> command-line `-object` (which _is_ documented in qemu-doc.texi).
> 
> Is it a good idea to send a patch to document the "props" in
> qapi/misc.json?  Or would it be needless duplication?

It is not practical at this time because object_add uses QOM object
properties and these are exclusively defined in code, not QAPI schema.

There's a long term todo item to use QAPI schema to define QOM objects,
which would then auto-generate the boilerplate QOM code, at which point
it all becomes self-documenting. That's basically lacking dev resources
to work on it though...


Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|