Make it clear that the name parameter to visit_start_struct()
has the same semantics as for visit_start_int().

Signed-off-by: Eric Blake <eblake@redhat.com>
---
 include/qapi/visitor.h | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/include/qapi/visitor.h b/include/qapi/visitor.h
index b0a048f..dc09cc7 100644
--- a/include/qapi/visitor.h
+++ b/include/qapi/visitor.h
@@ -60,13 +60,13 @@
  * visitors are declared here; the remaining visitors are generated in
  * qapi-visit.h.
  *
- * The @name parameter of visit_type_FOO() describes the relation
- * between this QAPI value and its parent container.  When visiting
- * the root of a tree, @name is ignored; when visiting a member of an
- * object, @name is the key associated with the value; when visiting a
- * member of a list, @name is NULL; and when visiting the member of an
- * alternate, @name should equal the name used for visiting the
- * alternate.
+ * The @name parameter of visit_type_FOO() and visit_start_OBJECT()
+ * describes the relation between this QAPI value and its parent
+ * container.  When visiting the root of a tree, @name is ignored;
+ * when visiting a member of an object, @name is the key associated
+ * with the value; when visiting a member of a list, @name is NULL;
+ * and when visiting the member of an alternate, @name should equal
+ * the name used for visiting the alternate.
  *
  * The visit_type_FOO() functions expect a non-null @obj argument;
  * they allocate *@obj during input visits, leave it unchanged on
-- 
2.9.4

Eric Blake <eblake@redhat.com> writes:

> Make it clear that the name parameter to visit_start_struct()
> has the same semantics as for visit_start_int().
>
> Signed-off-by: Eric Blake <eblake@redhat.com>
> ---
>  include/qapi/visitor.h | 14 +++++++-------
>  1 file changed, 7 insertions(+), 7 deletions(-)
>
> diff --git a/include/qapi/visitor.h b/include/qapi/visitor.h
> index b0a048f..dc09cc7 100644
> --- a/include/qapi/visitor.h
> +++ b/include/qapi/visitor.h
> @@ -60,13 +60,13 @@
>   * visitors are declared here; the remaining visitors are generated in
>   * qapi-visit.h.
>   *
> - * The @name parameter of visit_type_FOO() describes the relation
> - * between this QAPI value and its parent container.  When visiting
> - * the root of a tree, @name is ignored; when visiting a member of an
> - * object, @name is the key associated with the value; when visiting a
> - * member of a list, @name is NULL; and when visiting the member of an
> - * alternate, @name should equal the name used for visiting the
> - * alternate.
> + * The @name parameter of visit_type_FOO() and visit_start_OBJECT()

Our terminology is horrible:

    JSON object / QDict   / QAPI complex type (struct or union)
    JSON array  / QList   / QAPI array or list (used interchangeably)
    JSON value  / QObject / QAPI I'm-not-even-sure-what

Because of this mess, nobody knows what you mean when you say OBJECT.

visit_start_BAR()?

> + * describes the relation between this QAPI value and its parent
> + * container.  When visiting the root of a tree, @name is ignored;
> + * when visiting a member of an object, @name is the key associated
> + * with the value; when visiting a member of a list, @name is NULL;
> + * and when visiting the member of an alternate, @name should equal
> + * the name used for visiting the alternate.
>   *
>   * The visit_type_FOO() functions expect a non-null @obj argument;
>   * they allocate *@obj during input visits, leave it unchanged on

Reviewed-by: Markus Armbruster <armbru@redhat.com>

On 07/20/2017 05:00 AM, Markus Armbruster wrote:
> Eric Blake <eblake@redhat.com> writes:
> 
>> Make it clear that the name parameter to visit_start_struct()
>> has the same semantics as for visit_start_int().
>>
>> Signed-off-by: Eric Blake <eblake@redhat.com>
>> ---

>> + * The @name parameter of visit_type_FOO() and visit_start_OBJECT()
> 
> Our terminology is horrible:
> 
>     JSON object / QDict   / QAPI complex type (struct or union)
>     JSON array  / QList   / QAPI array or list (used interchangeably)
>     JSON value  / QObject / QAPI I'm-not-even-sure-what
> 
> Because of this mess, nobody knows what you mean when you say OBJECT.
> 
> visit_start_BAR()?

Works for me.

> Reviewed-by: Markus Armbruster <armbru@redhat.com>

Since you suggested it, I'll keep your R-b when I send v2.

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org