From: "Philippe Mathieu-Daudé" <philmd@redhat.com>
To: qemu-devel@nongnu.org
Cc: "Peter Maydell" <peter.maydell@linaro.org>,
"Daniel P . Berrange" <berrange@redhat.com>,
"Markus Armbruster" <armbru@redhat.com>,
"Philippe Mathieu-Daudé" <philmd@redhat.com>
Subject: [PATCH-for-6.2? 2/3] docs/devel/style: Improve Error** functions rST rendering
Date: Tue, 16 Nov 2021 16:13:16 +0100 [thread overview]
Message-ID: <20211116151317.2691125-3-philmd@redhat.com> (raw)
In-Reply-To: <20211116151317.2691125-1-philmd@redhat.com>
Signed-off-by: Philippe Mathieu-Daudé <philmd@redhat.com>
---
docs/devel/style.rst | 30 +++++++++++++++---------------
1 file changed, 15 insertions(+), 15 deletions(-)
diff --git a/docs/devel/style.rst b/docs/devel/style.rst
index 415a6b9d700..21f0f213193 100644
--- a/docs/devel/style.rst
+++ b/docs/devel/style.rst
@@ -602,16 +602,16 @@ Error handling and reporting
Reporting errors to the human user
----------------------------------
-Do not use printf(), fprintf() or monitor_printf(). Instead, use
-error_report() or error_vreport() from error-report.h. This ensures the
-error is reported in the right place (current monitor or stderr), and in
-a uniform format.
+Do not use ``printf()``, ``fprintf()`` or ``monitor_printf()``. Instead, use
+``error_report()`` or ``error_vreport()`` from error-report.h. This ensures
+the error is reported in the right place (current monitor or ``stderr``), and
+in a uniform format.
-Use error_printf() & friends to print additional information.
+Use ``error_printf()`` & friends to print additional information.
-error_report() prints the current location. In certain common cases
+``error_report()`` prints the current location. In certain common cases
like command line parsing, the current location is tracked
-automatically. To manipulate it manually, use the loc_``*``() from
+automatically. To manipulate it manually, use the ``loc_*()`` from
error-report.h.
Propagating errors
@@ -621,7 +621,7 @@ An error can't always be reported to the user right where it's detected,
but often needs to be propagated up the call chain to a place that can
handle it. This can be done in various ways.
-The most flexible one is Error objects. See error.h for usage
+The most flexible one is ``Error`` objects. See error.h for usage
information.
Use the simplest suitable method to communicate success / failure to
@@ -631,10 +631,10 @@ error, non-negative / -errno, non-null / null, or Error objects.
Example: when a function returns a non-null pointer on success, and it
can fail only in one way (as far as the caller is concerned), returning
null on failure is just fine, and certainly simpler and a lot easier on
-the eyes than propagating an Error object through an Error ``*````*`` parameter.
+the eyes than propagating an Error object through an ``Error **`` parameter.
Example: when a function's callers need to report details on failure
-only the function really knows, use Error ``*````*``, and set suitable errors.
+only the function really knows, use ``Error **``, and set suitable errors.
Do not report an error to the user when you're also returning an error
for somebody else to handle. Leave the reporting to the place that
@@ -643,17 +643,17 @@ consumes the error returned.
Handling errors
---------------
-Calling exit() is fine when handling configuration errors during
+Calling ``exit()`` is fine when handling configuration errors during
startup. It's problematic during normal operation. In particular,
-monitor commands should never exit().
+monitor commands should never ``exit()``.
-Do not call exit() or abort() to handle an error that can be triggered
+Do not call ``exit()`` or ``abort()`` to handle an error that can be triggered
by the guest (e.g., some unimplemented corner case in guest code
translation or device emulation). Guests should not be able to
terminate QEMU.
-Note that &error_fatal is just another way to exit(1), and &error_abort
-is just another way to abort().
+Note that ``&error_fatal`` is just another way to ``exit(1)``, and
+``&error_abort`` is just another way to ``abort()``.
trace-events style
--
2.31.1
next prev parent reply other threads:[~2021-11-16 15:18 UTC|newest]
Thread overview: 8+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-11-16 15:13 [PATCH-for-6.2? 0/3] docs/devel/style: Improve rST rendering Philippe Mathieu-Daudé
2021-11-16 15:13 ` [PATCH-for-6.2? 1/3] docs/devel/style: Improve GLib functions " Philippe Mathieu-Daudé
2021-11-18 10:58 ` Darren Kenny
2021-11-18 12:12 ` Philippe Mathieu-Daudé
2021-11-18 13:03 ` Daniel P. Berrangé
2021-11-16 15:13 ` Philippe Mathieu-Daudé [this message]
2021-11-16 15:13 ` [PATCH-for-6.2? 3/3] docs/devel/style: Improve types/qualifiers " Philippe Mathieu-Daudé
2021-11-18 11:04 ` Darren Kenny
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20211116151317.2691125-3-philmd@redhat.com \
--to=philmd@redhat.com \
--cc=armbru@redhat.com \
--cc=berrange@redhat.com \
--cc=peter.maydell@linaro.org \
--cc=qemu-devel@nongnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.