All of lore.kernel.org
 help / color / mirror / Atom feed
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



  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.