From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:47309) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XYdnW-0006y6-15 for qemu-devel@nongnu.org; Mon, 29 Sep 2014 12:27:42 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1XYdnR-0000Lg-Lu for qemu-devel@nongnu.org; Mon, 29 Sep 2014 12:27:37 -0400 Received: from mx1.redhat.com ([209.132.183.28]:45974) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XYdnR-0000IO-Ey for qemu-devel@nongnu.org; Mon, 29 Sep 2014 12:27:33 -0400 Message-ID: <54298867.3040604@redhat.com> Date: Mon, 29 Sep 2014 10:27:19 -0600 From: Eric Blake MIME-Version: 1.0 References: <1411794841-9672-1-git-send-email-arei.gonglei@huawei.com> <1411794841-9672-7-git-send-email-arei.gonglei@huawei.com> In-Reply-To: <1411794841-9672-7-git-send-email-arei.gonglei@huawei.com> Content-Type: multipart/signed; micalg=pgp-sha256; protocol="application/pgp-signature"; boundary="s5ap8WT5SmoDfR4ua1GCjuhCn2eEok9ds" Subject: Re: [Qemu-devel] [PATCH v3 6/7] qmp: print descriptions of object properties List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: arei.gonglei@huawei.com, qemu-devel@nongnu.org Cc: weidong.huang@huawei.com, aliguori@amazon.com, mst@redhat.com, armbru@redhat.com, luonengjun@huawei.com, peter.huangpeng@huawei.com, lcapitulino@redhat.com, stefanha@redhat.com, pbonzini@redhat.com, afaerber@suse.de This is an OpenPGP/MIME signed message (RFC 4880 and 3156) --s5ap8WT5SmoDfR4ua1GCjuhCn2eEok9ds Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable On 09/26/2014 11:14 PM, arei.gonglei@huawei.com wrote: > From: Gonglei >=20 > Add a new "description" field to DevicePropertyInfo. > The descriptions can serve as documentation in the code, > and they can be used to provide better help. For example: >=20 > $./qemu-system-x86_64 -device virtio-blk-pci,? >=20 > +++ b/qapi-schema.json > @@ -1615,11 +1615,12 @@ > # > # @name: the name of the property > # @type: the typename of the property > +# @description: the description of the property Please add a '(since 2.2)' designation. Will 'description' always be present (that is, do ALL properties have a description), or is it optional and only provided when a non-NULL description is available? [/me reads rest of patch] Yes, given your code, it looks like you meant for it to be optional. > # > # Since: 1.2 > ## > { 'type': 'DevicePropertyInfo', > - 'data': { 'name': 'str', 'type': 'str' } } > + 'data': { 'name': 'str', 'type': 'str', 'description': 'str' } } Therefore, this needs to be '*description'... > =20 > ## > # @device-list-properties: > diff --git a/qdev-monitor.c b/qdev-monitor.c > index 5ec6606..5ee6bf2 100644 > --- a/qdev-monitor.c > +++ b/qdev-monitor.c > @@ -213,9 +213,14 @@ int qdev_device_help(QemuOpts *opts) > } > =20 > for (prop =3D prop_list; prop; prop =3D prop->next) { > - error_printf("%s.%s=3D%s\n", driver, > + error_printf("%s.%s=3D%s", driver, > prop->value->name, > prop->value->type); > + if (prop->value->description) { =2E..and this needs to be 'prop->value->has_description'. We don't support NULL values of non-optional strings in QMP yet. > @@ -465,7 +466,9 @@ static DevicePropertyInfo *make_device_property_inf= o(ObjectClass *klass, > =20 > info =3D g_malloc0(sizeof(*info)); > info->name =3D g_strdup(prop->name); > - info->type =3D g_strdup(prop->info->legacy_name ?: prop->i= nfo->name); > + info->type =3D g_strdup(prop->info->name); > + info->description =3D prop->info->description ? > + g_strdup(prop->info->description) : NU= LL; This needs to be: info->has_description =3D !!prop->info->description; info->description =3D g_strdup(prop->info->description); (it's safe to call g_strdup(NULL), avoiding the need for ?: in the assignment). > return info; > } > klass =3D object_class_get_parent(klass); > @@ -475,6 +478,8 @@ static DevicePropertyInfo *make_device_property_inf= o(ObjectClass *klass, > info =3D g_malloc0(sizeof(*info)); > info->name =3D g_strdup(name); > info->type =3D g_strdup(default_type); > + info->description =3D description ? g_strdup(description) : NULL; Another place that should avoid the ?:, and set has_description. --=20 Eric Blake eblake redhat com +1-919-301-3266 Libvirt virtualization library http://libvirt.org --s5ap8WT5SmoDfR4ua1GCjuhCn2eEok9ds Content-Type: application/pgp-signature; name="signature.asc" Content-Description: OpenPGP digital signature Content-Disposition: attachment; filename="signature.asc" -----BEGIN PGP SIGNATURE----- Version: GnuPG v1 Comment: Public key at http://people.redhat.com/eblake/eblake.gpg iQEcBAEBCAAGBQJUKYhnAAoJEKeha0olJ0NqTZUH/0WCeWngdFwpOTyAqrq45cLl WLcUg2yEk16q2VMYiB9y6m6FJHM/MhL2S70eFtv9/riwbY3cgRhi1x9fsNQpQ37f qa9RJ+dcssln0j6wDdE7Q0HZWH3fQKJeEASz6Ej8mAkonvWEcpY1z9h9qaQDVE1x ai/jmXJMTjbNKqeJaDgY1IHmaZBHKux2kUeIZv/O5y4c4vjqFfooNAGEv5D+KdKT qSzDoEMSzhhMa7JNsr6p9gRGvWnxB+X/WVdfvfPnA98lv3apUXhtdkAAXuPr7/lI BNcv535O9REmTmWiXDKi0rw14lyKv7H5xZoLUVtOvGHySWzpp+k0CBEO2O/w6gc= =ZTle -----END PGP SIGNATURE----- --s5ap8WT5SmoDfR4ua1GCjuhCn2eEok9ds--