Coding standard updates.

Added some content, converted document to .rst.

1 files changed, 201 insertions, 63 deletions

diff --git a/notes/coding_standard.txt b/notes/coding_standard.rst
index 5b258f7..1deed03 100644
--- a/notes/coding_standard.txt
+++ b/notes/coding_standard.rst
@@ -13,11 +13,11 @@ not.  You being lazy doesn't count as a good reason.  Most, if not
 all, of these decisions are entirely arbitrary, but it's important for
 readability that we be consistent.
 
-The file .dir-locals.el in the libmaple root directory already ensures
-that many of these standards are followed by default in Emacs (but not
-on Windows, where it would need to be named _dir_locals.el, and no
-way, man).  There's also some elisp scattered about this file which
-will provide you additional help.
+The file ``.dir-locals.el`` in the libmaple root directory already
+ensures that many of these standards are followed by default in Emacs
+(but not on Windows, where it would need to be named
+``_dir_locals.el``, and no way, man).  There's also some elisp
+scattered about this file which will provide you additional help.
 
 Vim customizations to do the same thing would be nice (hint, hint)!
 
@@ -28,8 +28,10 @@ License
   source files for an example).  Copyright should go either to you or
   to LeafLabs, LLC.
 
+.. highlight:: scheme
+
   Emacs: if you don't like seeing the license, you should use
-  elide-head (which will hide it for you).  You can use the following:
+  elide-head (which will hide it for you).  You can use the following::
 
     (require 'elide-head)
     (setq programming-mode-hooks '(c-mode-hook c++-mode-hook))
@@ -43,23 +45,23 @@ License
 Whitespace/Indentation
 ----------------------
 
-- 4 space indents.  [Set in .dir-locals.el]
+- 4 space indents.  [Set in ``.dir-locals.el``]
 
 - Unix newlines. [Some exceptions are currently grandfathered in;
   these will go away in time.]
 
-- No tab characters. [Set in .dir-locals.el]
+- No tab characters. [Set in ``.dir-locals.el``]
 
 - No trailing whitespace.  For help getting this (and no tab
   characters) done automatically in Emacs, you can use this:
 
-    http://github.com/mbolivar/code-fascism
+      http://github.com/mbolivar/code-fascism
 
-  I hear tell you can get something similar in vim; ask around, I
+  I hear tell you can get something similar in Vim; ask around, I
   guess.
 
 - Files end in exactly one newline. [The presence of a newline at EOF
-  is already done by `c-require-final-newline' in recent versions of
+  is already done by ``c-require-final-newline`` in recent versions of
   Emacs.]
 
 - Exactly two newlines separate source paragraphs (you do separate
@@ -67,19 +69,152 @@ Whitespace/Indentation
 
 - The first line in a function is non-blank.
 
-- Don't indent C code within a conditionally-compiled extern "C"
-  block.  Emacs does this by default, which can be very annoying; you
-  can turn this behavior off with
+.. highlight:: cpp
 
-        (defun c-mode-inextern-lang-hook ()
-          (setcdr (assq 'inextern-lang c-offsets-alist) '-))
+- Exactly one space after ``if``, ``else``, ``for``, and ``while``,
+  before the following ``{`` or ``(``.  One space before ``else``,
+  after the preceding ``}``.  For example::
+
+      // This is good; we like this:
+      if (foo) {
+          while (quux) {
+              bar();
+          }
+      } else {
+          baz();
+      }
+
+      // THIS IS BAD! DON'T DO THIS:
+      if(foo){
+          while(quux){
+              bar();
+          }
+      }else{
+          baz();
+      }
+
+- Exactly one space in between binary arithmetic, logical, and
+  comparison operators and their operands, except for the . and ->
+  operators.  Examples::
+
+      // This is good:
+      int x = a + b * (c - d);
+      if (x != 0 && a > 7) {
+          SerialUSB.println(x);
+      }
+
+      // THIS IS BAD!
+      int x = a+b*(c-d);
+      if (x!=0 && a>7) {
+          SerialUSB.println(x);
+      }
+
+      // This is good:
+      uint32 adc_data = ADC1_BASE->DR;
+      SerialUSB.println(adc_data);
+
+      // THIS IS BAD!
+      uint32 adc_data = ADC1_BASE -> DR;
+      SerialUSB . println(adc_data);
 
-        (add-hook 'c-mode-hook c-mode-inextern-lang-hook)
+- No space between a unary operator and its operand.  Examples::
+
+      // Good:
+      x++;
+
+      // BAD!
+      x ++;
+
+      // Good:
+      y = -x;
+
+      // BAD!
+      y = - x;
+
+- If you need to break up a long line:
+
+  * Prefer to break up long expressions after a binary operator.  Example::
+
+      // Good:
+      if (some_really_long_conditional_wow_this_really_goes_on_forever ||
+          maybe_something_else_could_happen_too) {
+          ...
+      }
+
+      // BAD!
+      if (some_really_long_conditional_wow_this_really_goes_on_forever
+          || maybe_something_else_could_happen_too) {
+          ...
+      }
+
+  * When breaking up a function's arguments over multiple lines, align
+    the arguments on subsequent lines with the first argument.
+    Example::
+
+      // Good:
+      return_type value_i_got = function_with_a_really_long_name(argument1,
+                                                                 argument2,
+                                                                 argument3);
+
+      // BAD!
+      return_type value_i_got = function_with_a_really_long_name(argument1,
+          argument2,
+          argument3);
+
+      // BAD!
+      return_type value_i_got = function_with_a_really_long_name(argument1,
+                                                                    argument2,
+                                                                    argument3);
+
+- In function invocations, no space in between the function name and
+  the opening parenthesis.  Example::
+
+      // Good:
+      SerialUSB.println("Hello, world!");
+
+      // BAD!
+      SerialUSB.println ("Hello, world!");
+
+- Don't indent C code within a conditionally-compiled ``extern "C"``
+  block.  Example::
+
+      // Good:
+      #ifdef __cplusplus
+      extern "C"{
+      #endif
+
+      void some_c_function(void);
+
+      #ifdef __cplusplus
+      } // extern "C"
+      #endif
+
+      // BAD!
+      #ifdef __cplusplus
+      extern "C"{
+      #endif
+
+          void some_c_function(void);
+
+      #ifdef __cplusplus
+      } // extern "C"
+      #endif
+
+.. highlight:: scheme
+
+  Emacs does the "bad" behavior by default, which can be very
+  annoying.  You can turn this off with::
+
+      (defun c-mode-inextern-lang-hook ()
+          (setcdr (assq 'inextern-lang c-offsets-alist) '-))
+      (add-hook 'c-mode-hook c-mode-inextern-lang-hook)
 
 Comments
 --------
 
-- Multi-line comments are pretty flexible.  Any of these is fine:
+.. highlight:: c++
+
+- Multi-line comments are pretty flexible.  Any of these is fine::
 
     /* Comment starts here.
      * Continued lines have a '*' before them.
@@ -93,15 +228,16 @@ Comments
      * You can also place a newline after the opening "/*".
      */
 
-- Doxygen comments are multi-line comments that begin with /** instead.
+- Doxygen comments are multi-line comments that begin with ``/**``
+  instead.
 
-- Single-line comments on the same line are // in C++. (That's OK in C
-  as well).
+- Single-line comments on the same line are ``//`` in C++. (That's OK
+  in C as well).
 
-- Single-line comments on their own source line should be /* */ in C,
-  but can also be // in C++.  In Emacs, you can use M-;
-  (comment-dwim), and it'll Do What You Mean.  This isn't of great
-  importance.
+- Single-line comments on their own source line should be ``/* */`` in
+  C, but can also be ``//`` in C++.  (This isn't of great importance).
+  In Emacs, you can use M-; (comment-dwim), and it'll Do What You
+  Mean.
 
 Braces
 ------
@@ -112,7 +248,7 @@ Braces
 
   The only difference is that the opening brace of a function's
   definition occurs exactly one space character after the closing
-  parenthesis in that function's parameter list.  Example:
+  parenthesis in that function's parameter list.  Example::
 
       void func(void) {
           ...
@@ -124,66 +260,64 @@ Naming conventions
 There's always a fight about upper and lower case vs. underscores.
 We'll handle this as follows.
 
-- First, Dont_Mix_Like_This, because It_Looks_Really_Ugly, ok?
+- First, ``Dont_Mix_Like_This``, because ``It_Looks_Really_Ugly``, ok?
   [There's been some debate about this, and some exceptions are
   already grandfathered in, so in order to settle it, let's call this
   a "recommendation" instead of "requirement".]
 
-- Variables: Use underscores to separate words in C identifiers:
+- Variables: Use underscores to separate words in C identifiers::
 
     int some_example_name;
 
-  User-facing C++ variables should be camel cased (thisIsAnExample,
-  boardPWMPins, etc.), for consistency with the Arduino style.  It's
-  probably a good idea for you to case non-user facing C++ variables
-  in the C style; this will help disambiguate what's part of the
-  Wirish API and what's not.
+  User-facing C++ variables should be camel cased
+  (``thisIsAnExample``, ``boardPWMPins``, etc.), for consistency with
+  the Arduino style.  It's probably a good idea for you to case
+  non-user facing C++ variables in the C style; this will help
+  disambiguate what's part of the Wirish API and what's not.
 
-- Classes: Pascal case.  So ThisIsAClassName, but thisIsNot,
-  this_is_not, and like I said, Dont_You_DareTryANYTHING_STUPID.
+- Classes: Pascal case.  So ``ThisIsAClassName``, but ``thisIsNot``,
+  ``this_is_not``, and like I said,
+  ``Dont_You_DareTryANYTHING_STUPID``.
 
 - Functions: C functions are all lowercase, and words are separated by
   underscores.  C++ method names are camel cased.
 
-- Structs: Usually like variables (adc_dev, adc_reg_map, etc.), but
-  it's not crucial.  Don't feel obliged to put "_t" at the end of the
-  type name; we don't.
+- Structs: Usually like variables (``adc_dev``, ``adc_reg_map``,
+  etc.), but it's not crucial.  Don't feel obliged to put ``_t`` at
+  the end of the type name; we don't.
 
 - Macros and constants: all caps, separated by underscores.  C++
-  variables with the "const" qualifier generally aren't considered
+  variables with the ``const`` qualifier generally aren't considered
   "constants" for the purposes of this rule; i.e., they are cased
   according to the rules for variables.  We make an exception for
-  PIN_MAP, because it's the central Wirish data structure.
+  ``PIN_MAP``, because it's the central Wirish data structure.
 
-- foo.h gets #ifdef'ed to _FOO_H_.
+- foo.h gets ``#ifdef``\ 'ed to ``_FOO_H_``.
 
 - Acronyms: The case of letters in an acronym is determined by the
   case of the first letter in the acronym, which is determined by
-  following the above rules.  Examples:
+  following the above rules.  Examples::
 
+      // Good:
       void usb_func() { ... }
-
       void frob_usb_disc() { ... }
-
       class SomethingUSB {
           void usbInit();
           void initUSB();
       };
 
-  DON'T do this:
-
+      // BAD:
       class BadUsb { ... }; // say "GoodUSB" instead
-
       void swizzle_USB_disc() { ... } // say "swizzle_usb_disc" instead
 
 Documentation
 -------------
 
-- You must document your code.  At a bare minimum, this means Doxygen
-  comments on every user-facing function and type.  Additionally, you
-  need to individually document the fields and enumerator values of
-  structs and enums.  See any register map type's definition for an
-  example.
+- You **must** document your code.  At a bare minimum, this means
+  Doxygen comments on every user-facing function and type.
+  Additionally, you need to individually document the fields and
+  enumerator values of ``struct``\ s and ``enum``\ s.  See any
+  register map type's definition for an example.
 
 - For libmaple proper, you don't need comments for each register bit
   definition (for now).
@@ -206,14 +340,15 @@ Documentation
   source file informing future maintainers about it, so they'll pay
   extra attention when making changes.
 
-- For complicated peripherals, it would be nice if you put longer-form
-  comments into the libmaple notes/ directory, with a comment in the
-  corresponding .h file referring to it.  See libmaple/dac.h for an
-  example.
+- When adding peripheral support, it would be nice if you put
+  longer-form comments into the /notes/ directory, with a comment in
+  the corresponding .h file referring to it.  See /libmaple/dac.h for
+  an example.
 
-  This lets us keep the source files relatively clean while still
-  allowing new readers to have a starting point.  These longer-form
-  notes also have a habit of turning into user-facing documentation.
+  This lets us keep the source files relatively free of "introductory"
+  material, while allowing new readers a convenient starting point.
+  These longer-form notes also have a habit of turning into
+  user-facing documentation.
 
 - For libmaple proper (the pure C library under libmaple/); the
   convention is to document any user-facing function at the point where
@@ -227,6 +362,8 @@ General Formatting
 - Keep it 80-column clean.  That means Emacs says the largest column
   number=79.  You should turn on column number mode to help you out:
 
+.. highlight:: scheme
+
     (column-number-mode 1)
 
   You can get more help from lineker-mode:
@@ -265,11 +402,11 @@ Language Features and Compiler Extensions
 
 - Explicitly approved C++ features:
 
-  * Initializers that aren't constant; e.g. the gpio_dev* values in
-    PIN_MAPs.
+  * Initializers that aren't constant; e.g. the ``gpio_dev*`` values
+    in a ``PIN_MAP``.
 
   * Default arguments: e.g., the timeout argument defaulting to 0
-    (meaning to wait forever) in waitForButtonPress().
+    (meaning to wait forever) in ``waitForButtonPress()``.
 
 - Explicitly forbidden C++ features:
 
@@ -281,4 +418,5 @@ Language Features and Compiler Extensions
 
   * Operator overloading: Never allowed when it's just for style.
     Potentially allowed when you're implementing a class that models a
-    mathematical structure, and you'd like to implement e.g. operator+().
+    mathematical structure, and you'd like to implement
+    e.g. ``operator+()``.