From 376e1c98b4e1d34c216dba4b8c320b0c083a7a1c Mon Sep 17 00:00:00 2001
From: Marti Bolivar <mbolivar@leaflabs.com>
Date: Wed, 25 May 2011 01:53:29 -0400
Subject: Docs: Move toggleLED() and waitForButtonPress() examples.

These two examples from board-values.rst really belong in the
documentation for the functions they reference.
---
 source/lang/api/board-values.rst       | 42 +++++++++++-----------------------
 source/lang/api/toggleled.rst          | 22 +++++++++++++++++-
 source/lang/api/waitforbuttonpress.rst | 28 +++++++++++++++++++++--
 3 files changed, 60 insertions(+), 32 deletions(-)

(limited to 'source/lang/api')

diff --git a/source/lang/api/board-values.rst b/source/lang/api/board-values.rst
index 7198407..11b86a8 100644
--- a/source/lang/api/board-values.rst
+++ b/source/lang/api/board-values.rst
@@ -1,3 +1,5 @@
+.. highlight:: cpp
+
 .. _lang-board-values:
 
 Board-Specific Values
@@ -122,8 +124,9 @@ Constants
   default (i.e., they are in :ref:`boardUsedPins
   <lang-board-values-used-pins>`).  However, they can be used as
   ordinary GPIOs if you call the :ref:`lang-disabledebugports`
-  function.  (Be careful with this on the Maple, as writing to
-  ``BOARD_NJTRST_PIN`` may cause your board to reset!).
+  function.  (Be careful with this on the Maple and Maple RET6
+  Edition, as writing to ``BOARD_NJTRST_PIN`` :ref:`may cause your
+  board to reset <maple-nrst-pb4>`\ !).
 
 .. _lang-board-values-pwm-pins:
 
@@ -161,33 +164,14 @@ Examples
 :ref:`BOARD_LED_PIN <lang-board-values-led>` On the Maple, the
 built-in LED is connected to pin 13.  On the Maple Mini, however, it
 is connected to pin 33.  You can write a "blinky" program that works
-on all LeafLabs boards using ``BOARD_LED_PIN`` and :ref:`toggleLED()
-<lang-toggleled>`::
-
-    void setup() {
-        pinMode(BOARD_LED_PIN, OUTPUT);
-    }
-
-    void loop() {
-        toggleLED();
-        delay(100);
-    }
-
-:ref:`BOARD_BUTTON_PIN <lang-board-values-but>`: Similarly, you can
-write a single program that prints a message whenever the button is
-pressed which will work on all LeafLabs boards using
-``BOARD_BUTTON_PIN`` and :ref:`isButtonPressed()
-<lang-isbuttonpressed>`::
-
-    void setup() {
-        pinMode(BOARD_BUTTON_PIN, INPUT);
-    }
-
-    void loop() {
-        if (isButtonPressed()) {
-            SerialUSB.println("You pressed the button!");
-        }
-    }
+on both boards using :ref:`this example <lang-toggleled-example>`.
+
+:ref:`BOARD_BUTTON_PIN <lang-board-values-but>`: On the Maple, the
+built-in button is connected to pin 38.  On the Maple Mini, however,
+it is connected to pin 32.  :ref:`This example
+<lang-waitforbuttonpress-example>` shows how you can write a program
+that prints a message whenever the button is pressed which will work
+on all LeafLabs boards.
 
 See Also
 --------
diff --git a/source/lang/api/toggleled.rst b/source/lang/api/toggleled.rst
index 54a7d64..cad347f 100644
--- a/source/lang/api/toggleled.rst
+++ b/source/lang/api/toggleled.rst
@@ -1,15 +1,35 @@
+.. highlight:: cpp
+
 .. _lang-toggleled:
 
 toggleLED()
 ===========
 
-Switches the LED from off to on, or on to off.
+*Toggle* the built-in LED: switch it from off to on, or on to off.
 
 Library Documentation
 ---------------------
 
 .. doxygenfunction:: toggleLED
 
+Example
+-------
+
+.. _lang-toggleled-example:
+
+This example sets up the board's LED pin for output, then toggles the
+LED every 100 milliseconds::
+
+    void setup() {
+        pinMode(BOARD_LED_PIN, OUTPUT);
+    }
+
+    void loop() {
+        toggleLED();
+        delay(100);
+    }
+
+
 See Also
 --------
 
diff --git a/source/lang/api/waitforbuttonpress.rst b/source/lang/api/waitforbuttonpress.rst
index a5bd45c..0e0fbaf 100644
--- a/source/lang/api/waitforbuttonpress.rst
+++ b/source/lang/api/waitforbuttonpress.rst
@@ -1,16 +1,40 @@
+.. highlight:: cpp
+
 .. _lang-waitforbuttonpress:
 
 waitForButtonPress()
 ====================
 
-Wait for the board's built-in button (labeled BUT on the silkscreen)
-to be pressed, possibly with timeout.
+Wait for the board's built-in button to be pressed, possibly with
+timeout.  The button is labeled "BUT" on the board's silkscreen.  Its
+pin number is the constant :ref:`BOARD_BUTTON_PIN
+<lang-board-values-but>`.
 
 Library Documentation
 ---------------------
 
 .. doxygenfunction:: waitForButtonPress
 
+
+Example
+-------
+
+.. _lang-waitforbuttonpress-example:
+
+This example sets up the board's button pin as an input, then prints a
+message very time the button is pressed.
+
+::
+
+    void setup() {
+        pinMode(BOARD_BUTTON_PIN, INPUT);
+    }
+
+    void loop() {
+        waitForButtonPress();
+        SerialUSB.println("You pressed the button!");
+    }
+
 See Also
 --------
 
-- 
cgit v1.2.3