From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:60567) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1a9bkq-0003sm-Jk for qemu-devel@nongnu.org; Thu, 17 Dec 2015 11:50:14 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1a9bkn-0007We-Me for qemu-devel@nongnu.org; Thu, 17 Dec 2015 11:50:12 -0500 Received: from mx1.redhat.com ([209.132.183.28]:50154) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1a9bkn-0007WK-HJ for qemu-devel@nongnu.org; Thu, 17 Dec 2015 11:50:09 -0500 Received: from int-mx10.intmail.prod.int.phx2.redhat.com (int-mx10.intmail.prod.int.phx2.redhat.com [10.5.11.23]) by mx1.redhat.com (Postfix) with ESMTPS id 289C1C0B7E29 for ; Thu, 17 Dec 2015 16:50:09 +0000 (UTC) Received: from blackfin.pond.sub.org ([10.3.113.12]) by int-mx10.intmail.prod.int.phx2.redhat.com (8.14.4/8.14.4) with ESMTP id tBHGo7id013037 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=NO) for ; Thu, 17 Dec 2015 11:50:08 -0500 From: Markus Armbruster Date: Thu, 17 Dec 2015 17:49:46 +0100 Message-Id: <1450371004-26866-6-git-send-email-armbru@redhat.com> In-Reply-To: <1450371004-26866-1-git-send-email-armbru@redhat.com> References: <1450371004-26866-1-git-send-email-armbru@redhat.com> Subject: [Qemu-devel] [PATCH v2 05/23] error: Improve documentation around error_append_hint() List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: qemu-devel@nongnu.org While there, tighten its assertion. Signed-off-by: Markus Armbruster --- include/qapi/error.h | 19 +++++++++++++++++-- util/error.c | 2 +- 2 files changed, 18 insertions(+), 3 deletions(-) diff --git a/include/qapi/error.h b/include/qapi/error.h index b2362a5..048d947 100644 --- a/include/qapi/error.h +++ b/include/qapi/error.h @@ -18,6 +18,15 @@ * Create an error: * error_setg(&err, "situation normal, all fouled up"); * + * Create an error and add additional explanation: + * error_setg(&err, "invalid quark"); + * error_append_hint(&err, "Valid quarks are up, down, strange, " + * "charm, top, bottom\n"); + * + * Do *not* contract this to + * error_setg(&err, "invalid quark\n" + * "Valid quarks are up, down, strange, charm, top, bottom"); + * * Report an error to stderr: * error_report_err(err); * This frees the error object. @@ -26,6 +35,7 @@ * const char *msg = error_get_pretty(err); * do with msg what needs to be done... * error_free(err); + * Note that this loses hints added with error_append_hint(). * * Handle an error without reporting it (just for completeness): * error_free(err); @@ -128,6 +138,7 @@ ErrorClass error_get_class(const Error *err); * If @errp is anything else, *@errp must be NULL. * The new error's class is ERROR_CLASS_GENERIC_ERROR, and its * human-readable error message is made from printf-style @fmt, ... + * The resulting message should not contain newlines. */ #define error_setg(errp, fmt, ...) \ error_setg_internal((errp), __FILE__, __LINE__, __func__, \ @@ -184,7 +195,11 @@ void error_propagate(Error **dst_errp, Error *local_err); /** * Append a printf-style human-readable explanation to an existing error. - * May be called multiple times, and safe if @errp is NULL. + * @errp may be NULL, but neither &error_fatal nor &error_abort. + * Trivially the case if you call it only after error_setg() or + * error_propagate(). + * May be called multiple times. The resulting hint should end with a + * newline. */ void error_append_hint(Error **errp, const char *fmt, ...) GCC_FMT_ATTR(2, 3); @@ -218,7 +233,7 @@ void error_free_or_abort(Error **errp); /* * Convenience function to error_report() and free @err. */ -void error_report_err(Error *); +void error_report_err(Error *err); /* * Just like error_setg(), except you get to specify the error class. diff --git a/util/error.c b/util/error.c index 9b27c45..ebfb74b 100644 --- a/util/error.c +++ b/util/error.c @@ -132,7 +132,7 @@ void error_append_hint(Error **errp, const char *fmt, ...) return; } err = *errp; - assert(err && errp != &error_abort); + assert(err && errp != &error_abort && errp != &error_fatal); if (!err->hint) { err->hint = g_string_new(NULL); -- 2.4.3