shiftOut(), docs fixes

3 files changed, 99 insertions, 144 deletions

diff --git a/docs/source/lang/api/constants.rst b/docs/source/lang/api/constants.rst
index 72738b8..2e968e7 100644
--- a/docs/source/lang/api/constants.rst
+++ b/docs/source/lang/api/constants.rst
@@ -61,14 +61,6 @@ pin is configured as an ``INPUT`` (using :ref:`pinMode()
 <lang-digitalread>`, the microcontroller will report ``HIGH`` if a
 voltage of 3 volts or more is present at the pin.
 
-.. TODO? Following seems false; check it out sometime, leave out for now:
-
-.. A pin may also be configured as an ``INPUT`` with ``pinMode()``, and
-.. subsequently made ``HIGH`` with :ref:`digitalWrite()
-.. <lang-digitalwrite>`, this will set the internal pullup resistors,
-.. which will *steer* the input pin to a HIGH reading unless it is pulled
-.. LOW by external circuitry.
-
 When a pin is configured to ``OUTPUT`` with pinMode, and set to
 ``HIGH`` with :ref:`digitalWrite() <lang-digitalwrite>`, the pin is at
 3.3 volts. In this state it can *source* current, e.g. light an LED
diff --git a/docs/source/lang/api/shiftout.rst b/docs/source/lang/api/shiftout.rst
new file mode 100644
index 0000000..1d9ba12
--- /dev/null
+++ b/docs/source/lang/api/shiftout.rst
@@ -0,0 +1,99 @@
+.. highlight:: cpp
+
+.. _lang-shiftout:
+
+shiftOut()
+==========
+
+Shift out a byte of data, one bit at a time.
+
+.. contents:: Contents
+   :local:
+
+Library Documentation
+---------------------
+
+.. doxygenfunction:: shiftOut
+
+Discussion
+----------
+
+This is a software implementation.  There is also a hardware :ref:`SPI
+<spi>` library available which will be faster and consume less CPU
+cycles than this function.
+
+Note that the ``dataPin`` and ``clockPin`` must already be configured
+to :ref:`OUTPUT <lang-constants-output>` mode by a call to
+:ref:`pinMode() <lang-pinmode>`.
+
+Also note that since shiftOut() outputs 1 byte (8 bits) at a time, it
+requires multiple steps to output values larger than 255.
+
+Examples
+--------
+
+To use these examples, replace ``dataPin`` and ``clockPin`` with the
+numbers of the pins you want to use::
+
+    /* MSBFIRST example */
+
+    uint16 data = 500;
+    // shift out high byte
+    shiftOut(dataPin, clockPin, MSBFIRST, (data >> 8));
+    // shift out low byte
+    shiftOut(dataPin, clockPin, MSBFIRST, data);
+
+    /* LSBFIRST serial */
+
+    data = 500;
+    // shift out low byte
+    shiftOut(dataPin, clockPin, LSBFIRST, data);
+    // shift out high byte
+    shiftOut(dataPin, clockPin, LSBFIRST, (data >> 8));
+
+Arduino Tutorial Example
+------------------------
+
+This Arduino example runs unmodified on the Maple.  For accompanying
+circuit, see the `tutorial on controlling a 74HC595 shift register
+<http://arduino.cc/en/Tutorial/ShiftOut>`_.
+
+::
+
+    //**************************************************************//
+    //  Name    : shiftOutCode, Hello World                         //
+    //  Author  : Carlyn Maw, Tom Igoe                              //
+    //  Date    : 25 Oct, 2006                                      //
+    //  Version : 1.0                                               //
+    //  Notes   : Code for using a 74HC595 Shift Register           //
+    //          : to count from 0 to 255                            //
+    //**************************************************************//
+
+    // Pin connected to ST_CP of 74HC595
+    int latchPin = 8;
+    // Pin connected to SH_CP of 74HC595
+    int clockPin = 12;
+    // Pin connected to DS of 74HC595
+    int dataPin = 11;
+
+    void setup() {
+      // Set pins to output because they are addressed in the main loop
+      pinMode(latchPin, OUTPUT);
+      pinMode(clockPin, OUTPUT);
+      pinMode(dataPin, OUTPUT);
+    }
+
+    void loop() {
+      // Count up routine
+      for (int j = 0; j < 256; j++) {
+        // Ground latchPin and hold low for as long as you are transmitting
+        digitalWrite(latchPin, LOW);
+        shiftOut(dataPin, clockPin, LSBFIRST, j);
+        // Return the latch pin high to signal chip that it
+        // no longer needs to listen for information
+        digitalWrite(latchPin, HIGH);
+        delay(1000);
+      }
+    }
+
+.. include:: /lang/cc-attribution.txt
diff --git a/docs/source/lang/unimplemented/shiftout.rst b/docs/source/lang/unimplemented/shiftout.rst
deleted file mode 100644
index ff3852f..0000000
--- a/docs/source/lang/unimplemented/shiftout.rst
+++ /dev/null
@@ -1,136 +0,0 @@
-.. _lang-shiftout:
-
-shiftOut()
-==========
-
-Description
------------
-
-Shifts out a byte of data one bit at a time. Starts from either the
-most (i.e. the leftmost) or least (rightmost) significant bit. Each
-bit is written in turn to a data pin, after which a clock pin is
-pulsed to indicate that the bit is available.
-
-
-
-This is a software implementation; Arduino (as of 0019) also
-provides an `SPI library <http://arduino.cc/en/Reference/SPI>`_
-that uses the hardware implementation.
-
-
-
-Syntax
-------
-
-shiftOut(dataPin, clockPin, bitOrder, value)
-
-
-
-Parameters
-----------
-
-dataPin: the pin on which to output each bit (*int*)
-
-
-
-clockPin: the pin to toggle once the **dataPin** has been set to
-the correct value (*int*)
-
-
-
-bitOrder: which order to shift out the bits; either **MSBFIRST** or
-**LSBFIRST**.
-(Most Significant Bit First, or, Least Significant Bit First)
-
-
-
-value: the data to shift out. (*byte*)
-
-
-
-Returns
--------
-
-None
-
-
-
-Note
-----
-
-The **dataPin** and **clockPin** must already be configured as
-outputs by a call to
-`pinMode <http://arduino.cc/en/Reference/PinMode>`_\ ().
-
-
-
-**shiftOut** is currently written to output 1 byte (8 bits) so it
-requires a two step operation to output values larger than 255.
-
-::
-
-    // Do this for MSBFIRST serial
-    int data = 500;
-    // shift out highbyte
-    shiftOut(dataPin, clock, MSBFIRST, (data >> 8));
-    // shift out lowbyte
-    shiftOut(data, clock, MSBFIRST, data);
-
-    // Or do this for LSBFIRST serial
-    data = 500;
-    // shift out lowbyte
-    shiftOut(dataPin, clock, LSBFIRST, data);
-    // shift out highbyte
-    shiftOut(dataPin, clock, LSBFIRST, (data >> 8));
-
-
-
-Example
--------
-
-*For accompanying circuit, see the `tutorial on controlling a 74HC595 shift register <http://arduino.cc/en/Tutorial/ShiftOut>`_.*
-
-
-
-::
-
-    //**************************************************************//
-    //  Name    : shiftOutCode, Hello World                         //
-    //  Author  : Carlyn Maw,Tom Igoe                               //
-    //  Date    : 25 Oct, 2006                                      //
-    //  Version : 1.0                                               //
-    //  Notes   : Code for using a 74HC595 Shift Register           //
-    //          : to count from 0 to 255                            //
-    //****************************************************************
-
-    //Pin connected to ST_CP of 74HC595
-    int latchPin = 8;
-    //Pin connected to SH_CP of 74HC595
-    int clockPin = 12;
-    ////Pin connected to DS of 74HC595
-    int dataPin = 11;
-
-    void setup() {
-      //set pins to output because they are addressed in the main loop
-      pinMode(latchPin, OUTPUT);
-      pinMode(clockPin, OUTPUT);
-      pinMode(dataPin, OUTPUT);
-    }
-
-    void loop() {
-      //count up routine
-      for (int j = 0; j < 256; j++) {
-        //ground latchPin and hold low for as long as you are transmitting
-        digitalWrite(latchPin, LOW);
-        shiftOut(dataPin, clockPin, LSBFIRST, j);
-        //return the latch pin high to signal chip that it
-        //no longer needs to listen for information
-        digitalWrite(latchPin, HIGH);
-        delay(1000);
-      }
-    }
-
-
-
-
-.. include:: /lang/cc-attribution.txt