Skip to contentSkip to conversation

qapi: Make visit_next_list()'s comment less confusing

PATCH In review Markus Armbruster 2 participants 3 messages Aug 2, 2019 – Aug 12, 2019

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 qapi: Make visit_next_list()'s comment less confusing

visit_next_list() returns non-null on success, null on failure. The comment's phrasing "until NULL return or error occurs" is needlessly confusing. Scratch the "or error occurs" part.

---
 include/qapi/visitor.h | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)
include/qapi/visitor.h +4 -4
index 5b2ed3f202..c5b23851a1 100644
@@ -364,10 +364,10 @@ void visit_start_list(Visitor *v, const char *name, GenericList **list,
  * @tail must not be NULL; on the first call, @tail is the value of
  * *list after visit_start_list(), and on subsequent calls @tail must
  * be the previously returned value.  Should be called in a loop until
- * a NULL return or error occurs; for each non-NULL return, the caller
- * then calls the appropriate visit_type_*() for the element type of
- * the list, with that function's name parameter set to NULL and obj
- * set to the address of @tail->value.
+ * a NULL return; for each non-NULL return, the caller then calls the
+ * appropriate visit_type_*() for the element type of the list, with
+ * that function's name parameter set to NULL and obj set to the
+ * address of @tail->value.
  */
 GenericList *visit_next_list(Visitor *v, GenericList *tail, size_t size);
 
Signature · 1 line
2.21.0
Reviewed-by on v1 1/1
#1 lore raw
Quoted 8 lines · Markus Armbruster

visit_next_list() returns non-null on success, null on failure. The comment's phrasing "until NULL return or error occurs" is needlessly confusing. Scratch the "or error occurs" part.

---
 include/qapi/visitor.h | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)
Quoted 21 lines
include/qapi/visitor.h +4 -4
index 5b2ed3f202..c5b23851a1 100644
@@ -364,10 +364,10 @@ void visit_start_list(Visitor *v, const char *name, GenericList **list,
  * @tail must not be NULL; on the first call, @tail is the value of
  * *list after visit_start_list(), and on subsequent calls @tail must
  * be the previously returned value.  Should be called in a loop until
- * a NULL return or error occurs; for each non-NULL return, the caller
- * then calls the appropriate visit_type_*() for the element type of
- * the list, with that function's name parameter set to NULL and obj
- * set to the address of @tail->value.
+ * a NULL return; for each non-NULL return, the caller then calls the
+ * appropriate visit_type_*() for the element type of the list, with
+ * that function's name parameter set to NULL and obj set to the
+ * address of @tail->value.
  */
 GenericList *visit_next_list(Visitor *v, GenericList *tail, size_t size);
 
Signature · 3 lines
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3226
Virtualization:  qemu.org | libvirt.org