merge libmaple docs ("leaflabs-docs") into ./docs

In the past, libample documentation was forked out of this repository
because the documentation had increased in scope. For the librambutan,
and the rambutan project in general, we will try to keep documentation
closer to the source code, so the librambutan-specific documentation
should live here. Other sections of leaflabs-docs will be culled in a
following commit.

This merge attempts to maintain history by using a subtree strategy.
Followed directions at:

    http://nuclearsquid.com/writings/subtree-merging-and-you/

Full history for files should be accessible using the "--follow" flag to
git log, eg:

    git log --follow docs/source/adc.rst

It should be possible to pull patches from leaflabs-docs with:

    git pull -s subtree leaflabs-docs master

... at least until the docs in this repository diverge significantly.

1 files changed, 69 insertions, 0 deletions

diff --git a/docs/source/lang/api/delay.rst b/docs/source/lang/api/delay.rst
new file mode 100644
index 0000000..30bd436
--- /dev/null
+++ b/docs/source/lang/api/delay.rst
@@ -0,0 +1,69 @@
+.. highlight:: cpp
+
+.. _lang-delay:
+
+delay()
+=======
+
+Pauses the program for at least a given number of milliseconds. (There
+are 1000 milliseconds in a second.)
+
+Library Documentation
+---------------------
+
+.. doxygenfunction:: delay
+
+
+Discussion
+----------
+
+While it is easy to create a blinking LED with the ``delay()``
+function, and many sketches use short delays for such tasks as switch
+debouncing, the use of ``delay()`` in a sketch has significant
+drawbacks.  No other reading of sensors, mathematical calculations, or
+pin manipulation can go on during the delay function, so in effect, it
+brings most other activity to a halt. For alternative approaches to
+controlling timing see the :ref:`millis() <lang-millis>` function
+and the "Blink Without Delay" sketch cited :ref:`below
+<lang-delay-seealso>`\ . More knowledgeable programmers usually
+avoid the use of ``delay()`` for timing of events longer than tens of
+milliseconds, unless the sketch is very simple.
+
+Certain things *do* go on while the ``delay()`` function is
+controlling the STM32 chip, however, because the delay function does
+not disable interrupts. Serial communication that appears at the RX
+pin is recorded, PWM (see :ref:`pwmWrite() <lang-pwmwrite>`\ ) values
+and pin states are maintained, and :ref:`interrupts
+<lang-attachinterrupt>` will work as they should.
+
+
+Example
+-------
+
+::
+
+    void setup() {
+        // set up the built-in LED pin for output:
+        pinMode(BOARD_LED_PIN, OUTPUT);
+    }
+
+    void loop() {
+        digitalWrite(BOARD_LED_PIN, HIGH);   // sets the LED on
+        delay(1000);                         // waits for a second
+        digitalWrite(BOARD_LED_PIN, LOW);    // sets the LED off
+        delay(1000);                         // waits for a second
+    }
+
+.. _lang-delay-seealso:
+
+See Also
+--------
+
+- :ref:`millis() <lang-millis>`
+- :ref:`micros() <lang-micros>`
+- :ref:`delayMicroseconds() <lang-delayMicroseconds>`
+- (Arduino) `Blink Without Delay
+  <http://arduino.cc/en/Tutorial/BlinkWithoutDelay>`_ example (works
+  unmodified on Maple)
+
+.. include:: /arduino-cc-attribution.txt