Merge branch 'refactor'

This merges the libmaple refactor work into master.  The contents of
libmaple proper (/libmaple/) are almost completely incompatible with
previous APIs in master.  See /docs/source/libmaple/overview.rst for
more information on the new design.

Wirish incompatibilities are limited to the HardwareTimer class;
however, there are several new deprecations, most likely to be removed
in 0.1.0.

1 files changed, 39 insertions, 39 deletions

diff --git a/docs/source/lang/api/analogread.rst b/docs/source/lang/api/analogread.rst
index 35c6fbc..6665a94 100644
--- a/docs/source/lang/api/analogread.rst
+++ b/docs/source/lang/api/analogread.rst
@@ -20,53 +20,56 @@ 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
 --------------------
 
 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
 ----
 
 If the analog input pin is not connected to anything, the value
-returned by analogRead() will fluctuate based on a number of factors
-(e.g. the values of the other analog inputs, how close your hand is to
-the board, etc.) in a seemingly random way.
-
+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
 -------
 
- ::
+::
 
+    int analogPin = 3;     // Potentiometer wiper (middle terminal) connected
+                           // to analog pin 3. outside leads to ground and +3.3V.
+                           // You may have to change this value if your board
+                           // cannot perform ADC conversion on pin 3.
 
-    int analogPin = 3;     // potentiometer wiper (middle terminal) connected
-                           // to analog pin 3. outside leads to ground and +3.3V
     int val = 0;           // variable to store the value read
 
     void setup() {
       pinMode(analogPin, INPUT_ANALOG); // set up pin for analog input
-      SerialUSB.begin();                // set up usb virtual COM port
     }
 
     void loop() {
@@ -75,7 +78,6 @@ Example
                                       // a serial monitor
     }
 
-
 Arduino Compatibility
 ---------------------
 
@@ -97,23 +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 [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, opamps 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 note <adc>`
+- :ref:`ADC tutorial <adc>`
 - `(Arduino) Tutorial: Analog Input Pins <http://arduino.cc/en/Tutorial/AnalogInputPins>`_
 
-.. include:: cc-attribution.txt
+.. include:: /arduino-cc-attribution.txt