0.0.10 Documentation checkpoint.

The vast majority of the Maple-specific values have been pulled out of
the higher-level overview pages and replaced with refs into documents
under /docs/source/hardware/.

Much of the work that's left to be done in this regard is labeled with
versioned TODO and FIXME comments.

Suggestions from StephenFromNYC and gbulmer were incorporated from
this forum thread:

      http://forums.leaflabs.com/topic.php?id=703

1 files changed, 88 insertions, 7 deletions

diff --git a/docs/source/lang/api/hardwaretimer.rst b/docs/source/lang/api/hardwaretimer.rst
index 3f086ca..526beb6 100644
--- a/docs/source/lang/api/hardwaretimer.rst
+++ b/docs/source/lang/api/hardwaretimer.rst
@@ -10,8 +10,7 @@ built-in timer peripherals.  More information on these peripherals
 (including code examples) is available in the :ref:`timers reference
 <timers>`.
 
-.. FIXME update HardwareTimer documentation after redoing it in terms
-.. of the new timer interface.
+.. FIXME [0.0.10] Updated HardwareTimer documentation, with deprecation
 
 .. warning:: This class has been deprecated.  It is not available in
    the current build.
@@ -27,8 +26,7 @@ documented below on one of the predefined ``HardwareTimer`` instances.
 For example, to set the prescale factor on timer 1 to 5, call
 ``Timer1.setPrescaleFactor(5)``.
 
-.. TODO add code examples that people can copy and paste in case
-.. they're unfamiliar with namespace syntax
+.. TODO add tutorial-style examples
 
 .. cpp:class:: HardwareTimer
 
@@ -92,9 +90,8 @@ For example, to set the prescale factor on timer 1 to 5, call
    Set the given channel of this timer to the given :ref:`mode
    <lang-hardwaretimer-modes>`.  The parameter ``channel`` is one of
    1, 2, 3, and 4, and corresponds to the compare channel you would
-   like to set.  Refer to the full :ref:`pin mapping table
-   <pin-mapping-mega-table>` to match up timer channels and pin
-   numbers.
+   like to set.  Refer to your board's :ref:`master pin map
+   <gpio-pin-maps>` to match up timer channels and pin numbers.
 
 .. cpp:function:: void HardwareTimer::setChannel1Mode(TimerMode mode)
 
@@ -377,3 +374,87 @@ different.
 Other Functions
 ^^^^^^^^^^^^^^^
 .. doxygenfunction:: getTimer
+
+Examples
+^^^^^^^^
+
+**LED blink**::
+
+    #define LED_RATE 500000    // in microseconds; should give 0.5Hz toggles
+
+    void handler_led(void);
+
+    void setup()
+    {
+        // Set up the LED to blink
+        pinMode(BOARD_LED_PIN, OUTPUT);
+
+        // Setup Timer
+        Timer2.setChannel1Mode(TIMER_OUTPUTCOMPARE);
+        Timer2.setPeriod(LED_RATE); // in microseconds
+        Timer2.setCompare1(1);      // overflow might be small
+        Timer2.attachCompare1Interrupt(handler_led);
+    }
+
+    void loop() {
+        // Nothing! It's all in the interrupts
+    }
+
+    void handler_led(void) {
+        toggleLED();
+    }
+
+**Racing Counters**::
+
+    void handler_count1(void);
+    void handler_count2(void);
+
+    int count1 = 0;
+    int count2 = 0;
+
+    void setup()
+    {
+        // Set up BUT for input
+        pinMode(BOARD_BUTTON_PIN, INPUT_PULLUP);
+
+        // Setup Counting Timers
+        Timer3.setChannel1Mode(TIMER_OUTPUTCOMPARE);
+        Timer4.setChannel1Mode(TIMER_OUTPUTCOMPARE);
+        Timer3.pause();
+        Timer4.pause();
+        Timer3.setCount(0);
+        Timer4.setCount(0);
+        Timer3.setOverflow(30000);
+        Timer4.setOverflow(30000);
+        Timer3.setCompare1(1000);   // somewhere in the middle
+        Timer4.setCompare1(1000);
+        Timer3.attachCompare1Interrupt(handler1);
+        Timer4.attachCompare1Interrupt(handler2);
+        Timer3.resume();
+        Timer4.resume();
+    }
+
+    void loop() {
+        // Display the running counts
+        SerialUSB.print("Count 1: ");
+        SerialUSB.print(count1);
+        SerialUSB.print("\t\tCount 2: ");
+        SerialUSB.println(count2);
+
+        // Run... while BUT is held, pause Count2
+        for(int i = 0; i<1000; i++) {
+            if(digitalRead(BOARD_BUTTON_PIN)) {
+                Timer4.pause();
+            } else {
+                Timer4.resume();
+            }
+            delay(1);
+        }
+    }
+
+    void handler1(void) {
+        count1++;
+    }
+    void handler2(void) {
+        count2++;
+    }