From d70f3bfc6b0490e2e1f18552303f4ade8acabe32 Mon Sep 17 00:00:00 2001
From: Markus Armbruster <armbru@redhat.com>
Date: Sat, 3 Mar 2018 17:39:08 -0500
Subject: [PATCH] qobject-input-visitor: Document full_name_nth()

Backports commit 6c02258e143700314ebf268dae47eb23db17d1cf from qemu
---
 qemu/qapi/qobject-input-visitor.c | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/qemu/qapi/qobject-input-visitor.c b/qemu/qapi/qobject-input-visitor.c
index 672ecd9a..68dd3a4e 100644
--- a/qemu/qapi/qobject-input-visitor.c
+++ b/qemu/qapi/qobject-input-visitor.c
@@ -50,6 +50,17 @@ static QObjectInputVisitor *to_qiv(Visitor *v)
     return container_of(v, QObjectInputVisitor, visitor);
 }
 
+/*
+ * Find the full name of something @qiv is currently visiting.
+ * @qiv is visiting something named @name in the stack of containers
+ * @qiv->stack.
+ * If @n is zero, return its full name.
+ * If @n is positive, return the full name of the @n-th container
+ * counting from the top.  The stack of containers must have at least
+ * @n elements.
+ * The returned string is valid until the next full_name_nth(@v) or
+ * destruction of @v.
+ */
 static const char *full_name_nth(QObjectInputVisitor *qiv, const char *name,
                                  int n)
 {