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

[Kashyap Chamarthy <kchamart@redhat.com>]

On Wed, Jan 09, 2019 at 11:31:18AM +0100, Philippe Mathieu-Daudé wrote:
> Hi Kashyap,

Hi,

> On 1/9/19 9:51 AM, Kashyap Chamarthy wrote:

[...]

> > 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.

Even for developers who use QMP to implement higher layer tools, it
might take non-trivial amount of squinting to realize that it's a 1:1
mapping.  It should at least be mentioned in the relevant QMP doc
("explicit is better than implicit").  I'll submit a patch and see if it
flies. :-)

> 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

Yeah, that's a convenient example.  And in this specific case, it is
useful for those reading the code.

-- 
/kashyap