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

[Philippe Mathieu-Daudé]

Hi Kashyap,

On 1/9/19 9:51 AM, 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?

IMHO the 1:1 mapping is only obvious for developpers who implement such
commands and for 3rd party libs using QMP.
For end-users, a command-line comment is helpful.

This remind me of this patch:

https://lists.gnu.org/archive/html/qemu-devel/2018-11/msg06623.html

+/**
+ * QAuthZSimple:
+ *
+ * This authorization driver provides a simple mechanism
+ * for granting access based on an exact matched username.
+ *
+ * To create an instance of this class via QMP:
+ *
+ *  {
+ *    "execute": "object-add",
+ *    "arguments": {
+ *      "qom-type": "authz-simple",
+ *      "id": "authz0",
+ *      "parameters": {
+ *        "identity": "fred"
+ *      }
+ *    }
+ *  }
+ *
+ * Or via the command line
+ *
+ *   -object authz-simple,id=authz0,identity=fred
+ *
+ */

Regards,

Phil.