Coding standard updates.

Added some content, converted document to .rst.

1 files changed, 0 insertions, 284 deletions

diff --git a/notes/coding_standard.txt b/notes/coding_standard.txt
deleted file mode 100644
index 5b258f7..0000000
--- a/notes/coding_standard.txt
+++ /dev/null
@@ -1,284 +0,0 @@
-libmaple Coding Standards
-=========================
-
-Author: Marti Bolivar (mbolivar@leaflabs.com)
-
-LeafLabs team members are required to follow these when producing new
-code.  Community contributors to libmaple are strongly encouraged to
-do so; following these rules will greatly increase the probability
-that your patches will be folded in.
-
-In general, do it like this unless there's a really good reason why
-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.
-
-Vim customizations to do the same thing would be nice (hint, hint)!
-
-License
--------
-
-- Put an MIT license at the beginning of the file (look at any of our
-  source files for an example).  Copyright should go either to you or
-  to LeafLabs, LLC.
-
-  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:
-
-    (require 'elide-head)
-    (setq programming-mode-hooks '(c-mode-hook c++-mode-hook))
-    (add-to-list 'elide-head-headers-to-hide
-                 '("The MIT License" . "DEALINGS IN\n [*] THE SOFTWARE"))
-    (add-to-list 'elide-head-headers-to-hide
-                 '("The MIT License" . "DEALINGS IN THE\n...SOFTWARE"))
-    (dolist (hook programming-mode-hooks)
-      (add-hook hook (lambda () (elide-head))))
-
-Whitespace/Indentation
-----------------------
-
-- 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 trailing whitespace.  For help getting this (and no tab
-  characters) done automatically in Emacs, you can use this:
-
-    http://github.com/mbolivar/code-fascism
-
-  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
-  Emacs.]
-
-- Exactly two newlines separate source paragraphs (you do separate
-  your code into paragraphs, don't you?).
-
-- 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
-
-        (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:
-
-    /* Comment starts here.
-     * Continued lines have a '*' before them.
-     * The comment can end after the last line.
-     */
-
-    /* Comment starts here.
-     * The comment can end on the same line. */
-
-    /*
-     * You can also place a newline after the opening "/*".
-     */
-
-- 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 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.
-
-Braces
-------
-
-- Mostly 1TBS:
-
-      http://en.wikipedia.org/wiki/Indent_style#Variant:_1TBS
-
-  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:
-
-      void func(void) {
-          ...
-      }
-
-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?
-  [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:
-
-    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.
-
-- 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.
-
-- Macros and constants: all caps, separated by underscores.  C++
-  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.
-
-- 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:
-
-      void usb_func() { ... }
-
-      void frob_usb_disc() { ... }
-
-      class SomethingUSB {
-          void usbInit();
-          void initUSB();
-      };
-
-  DON'T do this:
-
-      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.
-
-- For libmaple proper, you don't need comments for each register bit
-  definition (for now).
-
-- Doxygen comments generally just belong on types, functions,
-  etc. that are part of the public user-facing API.  This generally
-  means that if there's ReST documentation for it under docs/source/,
-  it needs Doxygen comments, and that ReST should use Breathe to pull
-  that Doxygen comment out. (For more info on this, see docs/README).
-
-  There are some exceptions to this rule since Breathe isn't totally
-  mature yet and Sphinx's C++ domain is still in flux.  In these
-  cases, document the code "manually" in ReST.
-
-  This should be avoided if at all possible, since it creates a
-  maintenance burden of documenting things in two places at once, and
-  makes it easier for documentation to go stale.
-
-  If you do have to document something manually, put a comment in the
-  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.
-
-  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.
-
-- For libmaple proper (the pure C library under libmaple/); the
-  convention is to document any user-facing function at the point where
-  it is defined.  In particular, this means you should document an
-  externally-linked function defined in a .c file in that .c file, not
-  in the header file where it is declared to the user.
-
-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:
-
-    (column-number-mode 1)
-
-  You can get more help from lineker-mode:
-
-    http://www.helsinki.fi/~sjpaavol/programs/lineker.el
-
-  Just put lineker.el somewhere in your load-path, and:
-
-    (require 'lineker)
-    (dolist (hook '(c-mode-hook c++-mode-hook))
-      (add-hook hook (lambda () (lineker-mode 1))))
-
-Language Features and Compiler Extensions
------------------------------------------
-
-- In libmaple proper, aim for C99 compatibility.  Some GCC extensions
-  are OK, but let's not go crazy.  
-
-- If you'd like to get code into libmaple which uses a GCC extension
-  not already in use elsewhere, ask a LeafLabs developer (or another
-  one, if you are one) what they think about it first.
-
-- Explicitly approved GCC extensions:
-
-  * asm volatile:
-    http://gcc.gnu.org/onlinedocs/gcc/Extended-Asm.html
-
-  * Nested functions:
-    http://gcc.gnu.org/onlinedocs/gcc/Nested-Functions.html
-
-- In wirish, generally be very conservative when using C++ features
-  that aren't part of C.  We are forced to use C++ for Arduino
-  compatibility (and the general Arduino style of pretending that an
-  object is a library), but it's an angry beast, and we don't want to
-  provoke it.  The mantra is "C with classes".
-
-- Explicitly approved C++ features:
-
-  * Initializers that aren't constant; e.g. the gpio_dev* values in
-    PIN_MAPs.
-
-  * Default arguments: e.g., the timeout argument defaulting to 0
-    (meaning to wait forever) in waitForButtonPress().
-
-- Explicitly forbidden C++ features:
-
-  * Templates
-
-- C++ features that are conditionally allowed, but require explicit
-  approval from at least two libmaple developers (one of which may be
-  yourself):
-
-  * 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+().