From 9398bd49fed5ad9f13799094a61f39387923adff Mon Sep 17 00:00:00 2001
From: Markus Armbruster <armbru@redhat.com>
Date: Sat, 17 Feb 2018 20:49:03 -0500
Subject: [PATCH] error: Document how to accumulate multiple errors

Backports commit 8d780f43921feb7fd8d0b58f779a22d1265f2378 from qemu
---
 qemu/include/qapi/error.h | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/qemu/include/qapi/error.h b/qemu/include/qapi/error.h
index e9d7c40f..79fee178 100644
--- a/qemu/include/qapi/error.h
+++ b/qemu/include/qapi/error.h
@@ -69,6 +69,23 @@
  * But when all you do with the error is pass it on, please use
  *     foo(arg, errp);
  * for readability.
+ *
+ * Receive and accumulate multiple errors (first one wins):
+ *     Error *err = NULL, *local_err = NULL;
+ *     foo(arg, &err);
+ *     bar(arg, &local_err);
+ *     error_propagate(&err, local_err);
+ *     if (err) {
+ *         handle the error...
+ *     }
+ *
+ * Do *not* "optimize" this to
+ *     foo(arg, &err);
+ *     bar(arg, &err); // WRONG!
+ *     if (err) {
+ *         handle the error...
+ *     }
+ * because this may pass a non-null err to bar().
  */
 
 #ifndef ERROR_H