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, 29 insertions, 36 deletions

diff --git a/docs/source/lang/api/analogread.rst b/docs/source/lang/api/analogread.rst
index 7099b69..6665a94 100644
--- a/docs/source/lang/api/analogread.rst
+++ b/docs/source/lang/api/analogread.rst
@@ -20,32 +20,33 @@ Library Documentation
 Discussion
 ----------
 
-Reads the value from the specified analog pin.  The Maple board
-contains a 16-channel, 12-bit analog to digital converter.  This means
-that it will map input voltages between 0 and 3.3 volts into integer
-values between 0 and 4095.  This yields a resolution between readings
-of 3.3V / 4096 units, or 0.8 millivolts.  However, a number of factors
+Reads the value from the specified analog pin.  The Maple boards
+contain 16-channel, 12-bit analog to digital converters.  This means
+that a converter will map input voltages between 0 and 3.3 volts into
+integer values between 0 and 4095.  However, a number of factors
 interfere with getting full accuracy and precision.  For more
 information, see :ref:`adc`.
 
 Before calling analogRead() on a pin, that pin must first be
-configured for analog input, using :ref:`lang-pinMode` (you only
-have to do this once, so it's usually done in :ref:`lang-setup`\ ).
+configured for analog input, using :ref:`lang-pinMode`.  You only have
+to do this once, so it's usually done in :ref:`lang-setup`\ .
 
 Parameter Discussion
 --------------------
 
-.. FIXME generalize Maple-specific information
-
 The pin parameter is the number of the analog input pin to read from.
-Header pins on the Maple with ADC functionality (marked as "AIN" on
-the silkscreen) are:
-
-  0, 1, 2, 3, 10, 11, 12, 13, 15, 16, 17, 18, 19, 20, 27, 28
-
-Note that pins 3, 27, and 28 are not marked AIN on the silkscreen
-for Maple revisions through Rev 5, however, they **do work** as
-analog input pins.
+The pins which support analog to digital conversion have ``AIN``
+listed underneath their number on your board's silkscreen.  These pin
+numbers are available to your program in the :ref:`boardADCPins
+<lang-board-values-adc-pins>` board-specific array.  The number of
+pins which are capable of analog to digital conversion on your board
+is given by the ``BOARD_NR_ADC_PINS`` constant.  These values are
+documented for each board in the :ref:`Board Hardware Documentation
+<index-boards>` pages.
+
+.. note:: Pin 3 is not marked ``AIN`` on the silkscreen for Maple
+   revisions through Rev 5; however **it does work** as an analog
+   input pin.
 
 Note
 ----
@@ -55,7 +56,6 @@ returned by ``analogRead()`` will fluctuate due to a number of reasons
 (like the values of the other analog inputs, how close your hand is to
 the board, etc.) in a "random" way.
 
-
 Example
 -------
 
@@ -78,7 +78,6 @@ Example
                                       // a serial monitor
     }
 
-
 Arduino Compatibility
 ---------------------
 
@@ -100,27 +99,21 @@ shift <lang-bitshift>` the value of a Maple readout by 2, like so::
     // be aware that you're losing a lot of precision if you do this
     int adc_reading = analogRead(pin) >> 2;
 
-.. FIXME Mention Native can do analogReference(), when it's time
+.. FIXME [0.1.0] Mention that Native can do analogReference()
 
 On the Arduino, the input range and resolution can be changed using
-their implementation of `analogReference()
-<http://arduino.cc/en/Reference/AnalogReference>`_\ . Because of the
-way its hardware (as of Rev 5) was designed, it's not possible to
-implement analogReference on the Maple, so this function doesn't
-exist.  If your inputs lie in a different voltage range than 0V--3.3V,
-you'll need to bring them into that range before using
-``analogRead()``.  Some basic tools to accomplish this are `resistor
-dividers <http://en.wikipedia.org/wiki/Voltage_divider>`_ and `Zener
-diodes
-<http://en.wikipedia.org/wiki/Voltage_source#Zener_voltage_source>`_\
-. However, `operational amplifiers
-<http://en.wikipedia.org/wiki/Operational_amplifier>`_ and other
-powered components can also be used if greater precision is required.
-
-See also
+the `analogReference()
+<http://arduino.cc/en/Reference/AnalogReference>`_ function. Because
+of hardware restrictions, this function is not available on the Maple
+and Maple RET6 Edition.  If your inputs lie in a different voltage
+range than 0V--3.3V, you'll need to bring them into that range before
+using ``analogRead()``.  See the :ref:`ADC reference <adc-range>` for
+more information.
+
+See Also
 --------
 
 - :ref:`ADC tutorial <adc>`
 - `(Arduino) Tutorial: Analog Input Pins <http://arduino.cc/en/Tutorial/AnalogInputPins>`_
 
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt