[Qemu-devel] [PATCH 01/17] error: Update error_append_hint()'s documentation

[Greg Kurz <groug@kaod.org>]

error_setg() and error_propagate(), as well as their variants, cause
QEMU to terminate when called with &error_fatal or &error_abort. This
prevents to add hints since error_append_hint() isn't even called in
this case.

It means that error_append_hint() should only be used with a local
error object, and then propagate this local error to the caller.

Document this in <qapi/error.h> .

Signed-off-by: Greg Kurz <groug@kaod.org>
---
 include/qapi/error.h |   11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/include/qapi/error.h b/include/qapi/error.h
index 3f95141a01a8..28174329ba71 100644
--- a/include/qapi/error.h
+++ b/include/qapi/error.h
@@ -27,6 +27,13 @@
  *     error_setg(&err, "invalid quark\n"
  *                "Valid quarks are up, down, strange, charm, top, bottom.");
  *
+ * Dot *not* pass the errp parameter from the caller
+ *     error_setg(errp, "invalid quark");
+ *     error_append_hint(errp, "Valid quarks are up, down, strange, "
+ *                       "charm, top, bottom.\n");
+ * because error_setg() terminates QEMU if @errp is &error_fatal or
+ * &error_abort, and the hints are not even added.
+ *
  * Report an error to the current monitor if we have one, else stderr:
  *     error_report_err(err);
  * This frees the error object.
@@ -252,7 +259,9 @@ void error_prepend(Error **errp, const char *fmt, ...)
  * error message.
  * @errp may be NULL, but not &error_fatal or &error_abort.
  * Trivially the case if you call it only after error_setg() or
- * error_propagate().
+ * error_propagate(). CAUTION: error_setg() and error_propagate() do
+ * not return when passed &error_fatal. Always use a local error object
+ * and propagate it to the caller.
  * May be called multiple times.  The resulting hint should end with a
  * newline.
  */