readme and coding standard updates

2 files changed, 71 insertions, 45 deletions

diff --git a/libmaple/usb/README b/libmaple/usb/README
index f3970b6..540b1ea 100644
--- a/libmaple/usb/README
+++ b/libmaple/usb/README
@@ -5,16 +5,19 @@ The USB submodule of libmaple is responsible for:
     the USB isr, resetting the USB disc pin (used to tell the host
     were alive). Additionally, the USB submodule defines the virtual
     com port USB applications that is available to all user sketches
-    via Usb.print() and others.
+    via SerialUSB.print() and others.
 
 To use it:
-   Call Usb.init() to enable the IRQ channel, configure the clocks,
-     pull down usb_disc, and setup the vcom buffers
-   Usb.print/ln, available(), read(), write() implement the same
+
+   [This section is out of date.  Does SerialUSB.begin() do the same
+   thing as the old Usb.init()?]
+
+   SerialUSB.print/ln, available(), read(), write() implement the same
      interface as Serial1/2/3
-   
-   
+
+
 Current Status:
+
     Currently, the USB submodule relies on the low level core library
     provided by ST to access the USB peripheral registers and
     implement the USB transfer protocol for control endpoint
@@ -22,23 +25,27 @@ Current Status:
     unfortunately hard to untangle from this low level dependence, and
     when a new USB core library is written (to nix ST dependence)
     changes will likely have to be made to virtual com application
-    code. Ideally, the new core library should mimick the form of
-    MyUSB (LUFA), since this library (USB for AVR) is growing in
-    popularity and in example applications. Additionally, the USB lib
-    here relies on low level hardware functions that were just ripped
-    out of the bootloader code (for simplicity) but clearly this
-    should be replaced with direct accesses to functions provided
-    elsewhere in libmaple.
-
-    The virtual com port serves two important purposes. 1) is allows
-    serial data transfers between user sketches an a host computer. 2)
-    is allows the host machine to issue a system reset by asserting
-    the DTR signal. After reset, Maple will run the DFU bootloader for
-    a few seconds, during which the user can begin a DFU download
-    operation ('downloads' application binary into RAM/FLASH). This
-    without this virtual com port, it would be necessary to find an
-    alternative means to reset the chip in order to enable the
-    bootloader.
+    code. Ideally, the new core library should mimic the form of MyUSB
+    (LUFA), since this library (USB for AVR) is growing in popularity
+    and in example applications. Additionally, the USB lib here relies
+    on low level hardware functions that were just ripped out of the
+    bootloader code (for simplicity) but clearly this should be
+    replaced with direct accesses to functions provided elsewhere in
+    libmaple.
+
+    The virtual com port serves two important purposes.
+
+      1) It allows serial data transfers between user sketches an a
+         host computer.
+
+      2) It allows the host machine to issue a system reset by
+         asserting the DTR signal.
+
+    After reset, Maple will run the DFU bootloader for a few seconds,
+    during which the user can begin a DFU upload operation (uploads
+    application binary into RAM/FLASH). Thus, without this virtual com
+    port, it would be necessary to find an alternative means to reset
+    the chip in order to enable the bootloader.
 
     If you would like to develop your own USB application for whatever
     reason (uses faster isochronous enpoints for streaming audio, or
@@ -51,19 +58,19 @@ Current Status:
 
     It would be possible to build a compound USB device, that
     implements endpoints for both the virtual COM port as well as some
-    other components (mass sotrage etc.) however this turns out to be
-    a burden from the host driver side, as windows and *nix handle
+    other components (mass storage etc.).  However, this turns out to
+    be a burden from the host driver side, as Windows and *nix handle
     compound USB devices quite differently.
 
-    Be mindful that running the USB application isnt "free." The
+    Be mindful that enabling the USB peripheral isnt "free." The
     device must respond to periodic bus activity (every few
-    milliseconds) by servicing an ISR. Therefore the USB application
+    milliseconds) by servicing an ISR. Therefore, the USB application
     should be disabled inside of timing critical applications. In
     order to disconnect the device from the host, the USB_DISC pin can
-    be asserted (on Maple v1,2,3 this is GPIOC,12). Alternatively, the
-    NVIC can be directly configured to disable the USB LP/HP IRQ's
+    be asserted (on Maple this is GPIO C12). Alternatively, the NVIC
+    can be directly configured to disable the USB LP/HP IRQ's.
 
-    This library should exposed through usb.h, do not include any
+    This library should exposed through usb.h; do not include any
     other files direcly in your application.
 
     The files inside of usb_lib were provided by ST and are subject to
@@ -72,21 +79,22 @@ Current Status:
 
 Integration with libmaple:
 
-    The current USB lib is ported directly from the maple bootloader
-    code, adapted to be a virtual com rather than a DFU device. That
-    means several functions are redefined locally that could have been
-    pulled from elsewhere in libmaple. Thus, ths USB module depends
-    absolutely zero on libmaple, it even ensures that clocks are
-    configured correctly for its operation.
+    The current USB lib is ported from the Maple bootloader code,
+    adapted to be a virtual com rather than a DFU device. That means
+    several functions are redefined locally that could have been
+    pulled from elsewhere in libmaple.  Thus, ths USB module doesn't
+    have too many dependencies on libmaple.  It even ensures that
+    clocks are configured correctly for its operation.  However, over
+    time, some libmaple dependencies have crept in.
 
 Todo:
 
     - write custom low level USB stack to strip out any remaining
       dependence on ST code
     - remove dependence on hardware.c, since any functions here really
-      should have their own analogues elsewhere inside libmaple
+      should have their own analogs elsewhere inside libmaple
     - add a high level USB application library that would allow users
       to make their own HID/Mass Storage/Audio/Video devices.
-    - implement a Usb.link(SerialX) that forces a passthrough
+    - implement a SerialUSB.link(SerialX) that forces a passthrough
       the host computer virtual com to SerialX, and utilizes the
       line_config commands correctly (sets baud etc)
diff --git a/notes/coding_standard.txt b/notes/coding_standard.txt
index bab1e38..c0e4e4e 100644
--- a/notes/coding_standard.txt
+++ b/notes/coding_standard.txt
@@ -50,7 +50,7 @@ Whitespace
 
 - 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.]
+  Emacs.]
 
 - Exactly two newlines separate source paragraphs.
 
@@ -71,7 +71,7 @@ Comments
     /* comment starts here
      * the comment can end on the same line */
 
-- Doxygen comments are newline comments that begin with /** instead.
+- Doxygen comments begin with /** instead.
 
 - Single-line comments on the same line are // in c or c++.
 
@@ -114,9 +114,8 @@ because It_Looks_Really_Ugly, ok?
 - Structs: pick a style from "Variables" or "Classes" depending on how
   you mean it (since it might be either a simple record type, in which
   case do like c variables, or you might be faking an object in c, in
-  which case do like classes).  If it's in a typedef, should also
-  probably put _t at the end, but maybe you won't, and I don't really
-  feel too strongly about it.
+  which case do like classes).  If it's in a typedef, don't feel
+  obliged to put "_t" at the end of the name; we don't.
 
 - Acronyms: The case of letters in an acronym is determined by the
   case of the first letter in the acronym.  Examples:
@@ -139,11 +138,26 @@ because It_Looks_Really_Ugly, ok?
 Documentation
 -------------
 
-- Document your code, bitches!
+- Document your code.  This should go without saying.
 
 - At least put a doxygen comment with a nonempty @brief for every
   source file you add.  See the existing ones for examples.
 
+- 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
+  provides an opportunity for bad documentation to slip in, when the
+  code comments fall out of sync with the ReST docs.
+
 General Formatting
 ------------------
 
@@ -160,5 +174,9 @@ General Formatting
   Then put the file somewhere in your load-path, and
 
     (require 'lineker)
-    (dolist (hook programming-mode-hooks)
+    (dolist (hook '(c-mode-hook c++-mode-hook))
       (add-hook hook (lambda () (lineker-mode 1))))
+
+  There are only a few exceptional situations.  The most important one
+  is when specifying a lookup table like PIN_MAP where it'd be ugly to
+  split each entry over multiple lines.