From: "Philippe Mathieu-Daudé" <philmd@redhat.com>
To: qemu-devel@nongnu.org
Cc: "Peter Maydell" <peter.maydell@linaro.org>,
"Philippe Mathieu-Daudé" <philmd@redhat.com>,
"Daniel P . Berrange" <berrange@redhat.com>,
"Markus Armbruster" <armbru@redhat.com>,
"Darren Kenny" <darren.kenny@oracle.com>
Subject: [PATCH-for-6.2? v2 5/5] docs/devel/style: Misc rST rendering improvements
Date: Thu, 18 Nov 2021 15:57:16 +0100 [thread overview]
Message-ID: <20211118145716.4116731-6-philmd@redhat.com> (raw)
In-Reply-To: <20211118145716.4116731-1-philmd@redhat.com>
Signed-off-by: Philippe Mathieu-Daudé <philmd@redhat.com>
---
docs/devel/style.rst | 26 +++++++++++++-------------
1 file changed, 13 insertions(+), 13 deletions(-)
diff --git a/docs/devel/style.rst b/docs/devel/style.rst
index 0397971e528..1db50b70544 100644
--- a/docs/devel/style.rst
+++ b/docs/devel/style.rst
@@ -4,7 +4,7 @@ QEMU Coding Style
.. contents:: Table of Contents
-Please use the script checkpatch.pl in the scripts directory to check
+Please use the script ``checkpatch.pl`` in the scripts directory to check
patches before submitting.
Formatting and style
@@ -195,9 +195,9 @@ blocks) are generally not allowed; declarations should be at the beginning
of blocks.
Every now and then, an exception is made for declarations inside a
-#ifdef or #ifndef block: if the code looks nicer, such declarations can
+``#ifdef`` or ``#ifndef`` block: if the code looks nicer, such declarations can
be placed at the top of the block even if there are statements above.
-On the other hand, however, it's often best to move that #ifdef/#ifndef
+On the other hand, however, it's often best to move that ``#ifdef/#ifndef``
block to a separate function altogether.
Conditional statements
@@ -220,13 +220,13 @@ even when the constant is on the right.
Comment style
=============
-We use traditional C-style /``*`` ``*``/ comments and avoid // comments.
+We use traditional C-style ``/* */`` comments and avoid ``//`` comments.
-Rationale: The // form is valid in C99, so this is purely a matter of
+Rationale: The ``//`` form is valid in C99, so this is purely a matter of
consistency of style. The checkpatch script will warn you about this.
Multiline comment blocks should have a row of stars on the left,
-and the initial /``*`` and terminating ``*``/ both on their own lines:
+and the initial ``/*`` and terminating ``*/`` both on their own lines:
.. code-block:: c
@@ -274,11 +274,11 @@ Order include directives as follows:
#include "..." /* and finally QEMU headers. */
The "qemu/osdep.h" header contains preprocessor macros that affect the behavior
-of core system headers like <stdint.h>. It must be the first include so that
-core system headers included by external libraries get the preprocessor macros
-that QEMU depends on.
+of core system headers like ``<stdint.h>``. It must be the first include so
+that core system headers included by external libraries get the preprocessor
+macros that QEMU depends on.
-Do not include "qemu/osdep.h" from header files since the .c file will have
+Do not include ``"qemu/osdep.h"`` from header files since the .c file will have
already included it.
C types
@@ -352,9 +352,9 @@ casts, then reconsider or ask for help.
Pointers
--------
-Ensure that all of your pointers are "const-correct".
+Ensure that all of your pointers are "``const``-correct".
Unless a pointer is used to modify the pointed-to storage,
-give it the "const" attribute. That way, the reader knows
+give it the '``const``' attribute. That way, the reader knows
up-front that this is a read-only pointer. Perhaps more
importantly, if we're diligent about this, when you see a non-const
pointer, you're guaranteed that it is used to modify the storage
@@ -505,7 +505,7 @@ painful. These are:
the sign bit (ie it is an arithmetic shift, not a logical shift)
In addition, QEMU assumes that the compiler does not use the latitude
-given in C99 and C11 to treat aspects of signed '<<' as undefined, as
+given in C99 and C11 to treat aspects of signed '``<<``' as undefined, as
documented in the GNU Compiler Collection manual starting at version 4.0.
.. _autofree-ref:
--
2.31.1
next prev parent reply other threads:[~2021-11-18 15:02 UTC|newest]
Thread overview: 14+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-11-18 14:57 [PATCH-for-6.2? v2 0/5] docs/devel/style: Improve rST rendering Philippe Mathieu-Daudé
2021-11-18 14:57 ` [PATCH-for-6.2? v2 1/5] docs/devel/style: Render C types as monospaced text Philippe Mathieu-Daudé
2021-12-15 14:20 ` Alex Bennée
2021-11-18 14:57 ` [PATCH-for-6.2? v2 2/5] docs/devel/style: Improve Error** functions rST rendering Philippe Mathieu-Daudé
2021-12-15 14:26 ` Alex Bennée
2021-11-18 14:57 ` [PATCH-for-6.2? v2 3/5] docs/devel/style: Improve string format " Philippe Mathieu-Daudé
2021-12-15 14:31 ` Alex Bennée
2021-11-18 14:57 ` [PATCH-for-6.2? v2 4/5] docs/devel/style: Render C function names as monospaced text Philippe Mathieu-Daudé
2021-12-15 14:36 ` Alex Bennée
2021-11-18 14:57 ` Philippe Mathieu-Daudé [this message]
2021-12-15 14:39 ` [PATCH-for-6.2? v2 5/5] docs/devel/style: Misc rST rendering improvements Alex Bennée
2021-11-18 15:32 ` [PATCH-for-6.2? v2 0/5] docs/devel/style: Improve rST rendering Darren Kenny
2021-12-15 10:33 ` Philippe Mathieu-Daudé
2021-12-15 14:39 ` Alex Bennée
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=20211118145716.4116731-6-philmd@redhat.com \
--to=philmd@redhat.com \
--cc=armbru@redhat.com \
--cc=berrange@redhat.com \
--cc=darren.kenny@oracle.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 a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).