Improve external interrupts documentation.

Simplify and remove redundancies from external-interrupts.rst.  Move a
pin configuration detail from that page into the attachInterrupt() API
page (attachinterrupt.rst).  Fix and explain what's going on in the
example sketch in attachinterrupt.rst.

2 files changed, 40 insertions, 28 deletions

diff --git a/source/external-interrupts.rst b/source/external-interrupts.rst
index 60a87f1..1ab65be 100644
--- a/source/external-interrupts.rst
+++ b/source/external-interrupts.rst
@@ -5,13 +5,11 @@
 External Interrupts
 ===================
 
-External interrupts can be used to make a voltage change on a pin
-cause a function to be called.  Each :ref:`GPIO pin <gpio>` can be
-used to detect transitions, such as when the voltage goes from
-:ref:`LOW <lang-constants-low>` to :ref:`HIGH <lang-constants-high>`,
-or from ``HIGH`` to ``LOW``. This can be used to avoid checking for
-changes on a pin "manually" by waiting in a loop until the pin
-changes.
+External interrupts can be used to make a voltage change on a
+:ref:`pin <gpio>` (the pin going from :ref:`LOW <lang-constants-low>`
+to :ref:`HIGH <lang-constants-high>`, or vice-versa) to cause a
+function to be called.  This can be used to avoid checking for changes
+on a pin "manually" by waiting in a loop until the pin changes.
 
 .. _contents: Contents
    :local:
@@ -20,16 +18,16 @@ Overview
 --------
 
 External interrupts are often used to detect when events happen
-outside of the Maple. These can be used to tell Maple when events
-happen, such as when a sensor has data ready to be read, or when a
-button has been pushed.  When such an event happens, an interrupt is
-raised, and the Maple stops whatever it was doing to react to it by
-calling a function (called an *interrupt handler*) which you specify
-using :ref:`lang-attachinterrupt`.
+outside of the Maple.  Example events include when a sensor has data
+ready to be read, or when a button has been pushed.  When such an
+event happens, an interrupt is raised, and the Maple stops whatever it
+was doing (it is "interrupted"), and reacts to the event by calling a
+function (called an *interrupt handler*) which you specify using
+:ref:`lang-attachinterrupt`.
 
 .. _external-interrupts-exti-line:
 
-Every pin can generate an external interrupt, but there are some
+Any pin can be used for external interrupts, but there are some
 restrictions.  At most 16 different external interrupts can be used at
 one time.  Further, you can't just pick any 16 pins to use.  This is
 because every pin on the Maple connects to what is called an *EXTI
@@ -45,12 +43,6 @@ EXTI lines:
 * :ref:`Maple RET6 Edition <maple-ret6-exti-map>`
 * :ref:`Maple Mini <maple-mini-exti-map>`
 
-.. note::
-
-   You should set the :ref:`pin mode <lang-pinmode>` of your desired
-   pin to an input mode (e.g. ``INPUT``, ``INPUT_PULLUP``,
-   ``INPUT_PULLDOWN``).
-
 Function Reference
 ------------------
 
diff --git a/source/lang/api/attachinterrupt.rst b/source/lang/api/attachinterrupt.rst
index 39902ac..58e4764 100644
--- a/source/lang/api/attachinterrupt.rst
+++ b/source/lang/api/attachinterrupt.rst
@@ -41,6 +41,12 @@ Library Documentation
 
 .. doxygentypedef:: voidFuncPtr
 
+.. note::
+
+   You should set the :ref:`pin mode <lang-pinmode>` of your desired
+   pin to an input mode (e.g. ``INPUT``, ``INPUT_PULLUP``,
+   ``INPUT_PULLDOWN``).
+
 Discussion
 ----------
 
@@ -50,31 +56,45 @@ Because the function will run in interrupt context, inside of it,
 the function may be lost. You should declare as ``volatile`` any
 global variables that you modify within the attached function.
 
-There are a few limits you should be aware of if you're using more
-than one interrupt at a time; the :ref:`External Interrupts
-<external-interrupts-exti-line>` page has more information.
+There are some limits you should be aware of if you're using
+``attachInterrupt()`` with more than one pin; the :ref:`External
+Interrupts <external-interrupts-exti-line>` page has more information.
 
 Example
 -------
 
- ::
+The following example blinks the LED any time pin 0 changes from
+``HIGH`` to ``LOW`` or vice versa. ::
 
     volatile int state = LOW; // must declare volatile, since it's
                               // modified within the blink() handler
 
     void setup() {
-      pinMode(BOARD_LED_PIN, OUTPUT);
-      attachInterrupt(0, blink, CHANGE);
+        pinMode(BOARD_LED_PIN, OUTPUT);
+        pinMode(0, INPUT);
+        attachInterrupt(0, blink, CHANGE);
     }
 
     void loop() {
-      digitalWrite(BOARD_LED_PIN, state);
+        digitalWrite(BOARD_LED_PIN, state);
     }
 
     void blink() {
-      state = !state;
+        if (state == HIGH) {
+            state = LOW;
+        } else { // state must be LOW
+            state = HIGH;
+        }
     }
 
+In this example, the function ``blink()`` is the interrupt handler.
+Whenever the state on pin 0 changes, ``blink()`` gets called.  It
+reacts to the change by changing the ``state`` variable to ``LOW`` if
+it is ``HIGH``, and to ``HIGH`` if it is ``LOW``.  It then exits,
+letting the board get back to calling ``loop()``.  Since ``loop()``
+sets the LED pin to whatever ``state`` is, changing the voltage on pin
+0 will toggle the LED.
+
 Arduino Compatibility
 ---------------------