1 files changed, 46 insertions, 38 deletions

diff --git a/docs/CODE_STYLE.md b/docs/CODE_STYLE.md
index ba5f71026..2d275cd7d 100644
--- a/docs/CODE_STYLE.md
+++ b/docs/CODE_STYLE.md
@@ -9,8 +9,8 @@ style is more important than individual contributors having their own personal
 tastes satisfied.
 
 Our C code has a few style rules. Most of them are verified and upheld by the
-`lib/checksrc.pl` script. Invoked with `make checksrc` or even by default by
-the build system when built after `./configure --enable-debug` has been used.
+"lib/checksrc.pl" script. Invoked with "make checksrc" or even by default by
+the build system when built after "./configure --enable-debug" has been used.
 
 It is normally not a problem for anyone to follow the guidelines, as you just
 need to copy the style already used in the source code and there are no
@@ -44,8 +44,8 @@ open brace.
 
 ## Comments
 
-Since we write C89 code, `//` comments are not allowed. They weren't
-introduced in the C standard until C99. We use only `/*` and `*/` comments:
+Since we write C89 code, **//** comments are not allowed. They weren't
+introduced in the C standard until C99. We use only **/* comments */**.
 
     /* this is a comment */
 
@@ -87,8 +87,8 @@ For functions the opening brace should be on a separate line:
 
 ## 'else' on the following line
 
-When adding an `else` clause to a conditional expression using braces, we add
-it on a new line after the closing brace. Like this:
+When adding an **else** clause to a conditional expression using braces, we
+add it on a new line after the closing brace. Like this:
 
     if(age < 40) {
       /* clearly a youngster */
@@ -149,8 +149,8 @@ and NEVER:
 
 ## Space around operators
 
-Please use spaces on both sides of operators in C expressions.  Postfix `(),
-[], ->, ., ++, --` and Unary `+, - !, ~, &` operators excluded they should
+Please use spaces on both sides of operators in C expressions.  Postfix **(),
+[], ->, ., ++, --** and Unary **+, - !, ~, &** operators excluded they should
 have no space.
 
 Examples:
@@ -167,63 +167,71 @@ Examples:
     complement = ~bits;
     empty = (!*string) ? TRUE : FALSE;
 
+## No parentheses for return values
+
+We use the 'return' statement without extra parentheses around the value:
+
+    int works(void)
+    {
+      return TRUE;
+    }
+
+## Parentheses for sizeof arguments
+
+When using the sizeof operator in code, we prefer it to be written with
+parentheses around its argument:
+
+    int size = sizeof(int);
+
 ## Column alignment
 
-Some statements cannot be completed on a single line because the line would
-be too long, the statement too hard to read, or due to other style guidelines
+Some statements cannot be completed on a single line because the line would be
+too long, the statement too hard to read, or due to other style guidelines
 above. In such a case the statement will span multiple lines.
 
 If a continuation line is part of an expression or sub-expression then you
 should align on the appropriate column so that it's easy to tell what part of
 the statement it is. Operators should not start continuation lines. In other
-cases follow the 2-space indent guideline. Here are some examples from libcurl:
+cases follow the 2-space indent guideline. Here are some examples from
+libcurl:
 
-~~~c
     if(Curl_pipeline_wanted(handle->multi, CURLPIPE_HTTP1) &&
        (handle->set.httpversion != CURL_HTTP_VERSION_1_0) &&
        (handle->set.httpreq == HTTPREQ_GET ||
         handle->set.httpreq == HTTPREQ_HEAD))
       /* didn't ask for HTTP/1.0 and a GET or HEAD */
       return TRUE;
-~~~
 
-~~~c
-  case CURLOPT_KEEP_SENDING_ON_ERROR:
-    data->set.http_keep_sending_on_error = (0 != va_arg(param, long)) ?
-                                           TRUE : FALSE;
-    break;
-~~~
+If no parenthesis, use the default indent:
 
-~~~c
     data->set.http_disable_hostname_check_before_authentication =
       (0 != va_arg(param, long)) ? TRUE : FALSE;
-~~~
-
-~~~c
-  if(option) {
-    result = parse_login_details(option, strlen(option),
-                                 (userp ? &user : NULL),
-                                 (passwdp ? &passwd : NULL),
-                                 NULL);
-  }
-~~~
-
-~~~c
-        DEBUGF(infof(data, "Curl_pp_readresp_ %d bytes of trailing "
-                     "server response left\n",
-                     (int)clipamount));
-~~~
+
+Function invoke with an open parenthesis:
+
+    if(option) {
+      result = parse_login_details(option, strlen(option),
+                                   (userp ? &user : NULL),
+                                   (passwdp ? &passwd : NULL),
+                                   NULL);
+    }
+
+Align with the "current open" parenthesis:
+
+    DEBUGF(infof(data, "Curl_pp_readresp_ %d bytes of trailing "
+                 "server response left\n",
+                 (int)clipamount));
 
 ## Platform dependent code
 
-Use `#ifdef HAVE_FEATURE` to do conditional code. We avoid checking for
+Use **#ifdef HAVE_FEATURE** to do conditional code. We avoid checking for
 particular operating systems or hardware in the #ifdef lines. The HAVE_FEATURE
 shall be generated by the configure script for unix-like systems and they are
 hard-coded in the config-[system].h files for the others.
 
 We also encourage use of macros/functions that possibly are empty or defined
 to constants when libcurl is built without that feature, to make the code
-seamless. Like this style where the `magic()` function works differently
+seamless. Like this example where the **magic()** function works differently
 depending on a build-time conditional:
 
     #ifdef HAVE_MAGIC