[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Qemu-devel] [PULL 21/41] error: Improve documentation
From: |
Markus Armbruster |
Subject: |
[Qemu-devel] [PULL 21/41] error: Improve documentation |
Date: |
Wed, 13 Jan 2016 16:43:19 +0100 |
While there, tighten error_append_hint()'s assertion.
Signed-off-by: Markus Armbruster <address@hidden>
Message-Id: <address@hidden>
Reviewed-by: Eric Blake <address@hidden>
---
include/qapi/error.h | 20 ++++++++++++++++++--
util/error.c | 2 +-
util/qemu-error.c | 8 ++++----
3 files changed, 23 insertions(+), 7 deletions(-)
diff --git a/include/qapi/error.h b/include/qapi/error.h
index 1480f59..b18a608 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);
@@ -142,6 +152,8 @@ ErrorClass error_get_class(const Error *err);
* If @errp is anything else, address@hidden 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 be a single phrase, with no newline or
+ * trailing punctuation.
*/
#define error_setg(errp, fmt, ...) \
error_setg_internal((errp), __FILE__, __LINE__, __func__, \
@@ -198,7 +210,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 not &error_fatal or &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);
@@ -232,7 +248,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);
diff --git a/util/qemu-error.c b/util/qemu-error.c
index c1574bb..ecf5708 100644
--- a/util/qemu-error.c
+++ b/util/qemu-error.c
@@ -200,8 +200,8 @@ static void error_print_loc(void)
bool enable_timestamp_msg;
/*
* Print an error message to current monitor if we have one, else to stderr.
- * Format arguments like vsprintf(). The result should not contain
- * newlines.
+ * Format arguments like vsprintf(). The resulting message should be
+ * a single phrase, with no newline or trailing punctuation.
* Prepend the current location and append a newline.
* It's wrong to call this in a QMP monitor. Use error_setg() there.
*/
@@ -224,8 +224,8 @@ void error_vreport(const char *fmt, va_list ap)
/*
* Print an error message to current monitor if we have one, else to stderr.
- * Format arguments like sprintf(). The result should not contain
- * newlines.
+ * Format arguments like sprintf(). The resulting message should be a
+ * single phrase, with no newline or trailing punctuation.
* Prepend the current location and append a newline.
* It's wrong to call this in a QMP monitor. Use error_setg() there.
*/
--
2.4.3
- [Qemu-devel] [PULL 00/41] Error reporting patches for 2016-01-13, Markus Armbruster, 2016/01/13
- [Qemu-devel] [PULL 01/41] error: Document how to accumulate multiple errors, Markus Armbruster, 2016/01/13
- [Qemu-devel] [PULL 03/41] hw: Inline the qdev_prop_set_drive_nofail() wrapper, Markus Armbruster, 2016/01/13
- [Qemu-devel] [PULL 09/41] error: Don't append a newline when printing the error hint, Markus Armbruster, 2016/01/13
- [Qemu-devel] [PULL 08/41] raven: Mark use of hw_error() in realize() FIXME, Markus Armbruster, 2016/01/13
- [Qemu-devel] [PULL 15/41] audio: Clean up inappropriate and unreachable use of hw_error(), Markus Armbruster, 2016/01/13
- [Qemu-devel] [PULL 24/41] test-throttle: Simplify qemu_init_main_loop() error handling, Markus Armbruster, 2016/01/13
- [Qemu-devel] [PULL 20/41] error: Use error_report_err() instead of ad hoc prints, Markus Armbruster, 2016/01/13
- [Qemu-devel] [PULL 13/41] isa: Clean up error handling around isa_bus_new(), Markus Armbruster, 2016/01/13
- [Qemu-devel] [PULL 18/41] error: Use error_report_err() where appropriate (again), Markus Armbruster, 2016/01/13
- [Qemu-devel] [PULL 21/41] error: Improve documentation,
Markus Armbruster <=
- [Qemu-devel] [PULL 36/41] vhdx: Fix "log that needs to be replayed" error message, Markus Armbruster, 2016/01/13
- [Qemu-devel] [PULL 02/41] Use error_fatal to simplify obvious fatal errors, Markus Armbruster, 2016/01/13
- [Qemu-devel] [PULL 05/41] omap: Don't use hw_error() in device init() methods, Markus Armbruster, 2016/01/13
- [Qemu-devel] [PULL 07/41] etraxfs_eth: Don't use hw_error() in init() method, Markus Armbruster, 2016/01/13
- [Qemu-devel] [PULL 11/41] sysbus: Don't use hw_error() in machine_init_done_notifiers, Markus Armbruster, 2016/01/13
- [Qemu-devel] [PULL 17/41] qemu-nbd: Replace BSDism <err.h> by error_report(), Markus Armbruster, 2016/01/13
- [Qemu-devel] [PULL 28/41] error: Use error_prepend() where it makes obvious sense, Markus Armbruster, 2016/01/13
- [Qemu-devel] [PULL 19/41] error: Use error_report_err() instead of monitor_printf(), Markus Armbruster, 2016/01/13
- [Qemu-devel] [PULL 35/41] pci-assign: Clean up "Failed to assign" error messages, Markus Armbruster, 2016/01/13
- [Qemu-devel] [PULL 06/41] arm_mptimer: Don't use hw_error() in realize() method, Markus Armbruster, 2016/01/13