Docs: Updating Servo docs.

1 files changed, 22 insertions, 88 deletions

diff --git a/source/libs/servo.rst b/source/libs/servo.rst
index 891f151..3b96467 100644
--- a/source/libs/servo.rst
+++ b/source/libs/servo.rst
@@ -5,8 +5,6 @@
 Servo
 =====
 
-.. FIXME [0.0.10] this is out of date
-
 This documents the Servo library for controlling RC servomotors.  It
 is implemented as a thin layer over the built-in :ref:`timer
 peripherals <timers>`.
@@ -31,83 +29,15 @@ servomotor attached to pin 9, you could write ::
 
      servo.attach(9);
 
-.. cpp:class:: Servo
-
-   Class for controlling RC servomotors via :ref:`timers <timers>`.
+.. TODO [0.0.10] figure out the cpp domain well enough to replace
+.. references here
 
 .. _libs-servo-attach:
 
-.. cpp:function:: bool Servo::attach(uint8 pin, uint16 min, uint16 max)
-
-   Attach this Servo object to the given ``pin``.  The pin must be
-   capable of PWM.  You can check this by seeing if "PWM" is written
-   next to its number on the Maple silkscreen, or by consulting the
-   :ref:`pwmWrite() <lang-pwmwrite>` documentation.
-
-   Sets this pin's :ref:`mode <lang-pinmode>` to :ref:`PWM
-   <lang-pinmode-wiringpinmode>`, and returns true if successful.
-   Does nothing and returns false if the pin doesn't support PWM.
-
-   Parameter ``min`` is the pulse width corresponding to 0 degrees;
-   ``max`` is the pulse width corresponding to 180 degrees (both are
-   in microseconds).
-
-.. cpp:function:: bool Servo::attach(uint8 pin)
-
-   Equivalent to :ref:`attach(pin, 544, 2400) <libs-servo-attach>`.
-
 .. _libs-servo-attached:
 
-.. cpp:function:: int Servo::attached() const
-
-   If currently attached (via :ref:`attach() <libs-servo-attach>`) to
-   a pin, returns that pin's number.  Returns ``NOT_ATTACHED``
-   otherwise.
-
-.. cpp:function:: bool Servo::detach()
-
-   If this Servo object is currently attached to pin, stops driving
-   the servo by setting a zero pulse width (this is accomplished by
-   setting the associated :ref:`channel mode
-   <lang-hardwaretimer-setchannelmode>` to ``TIMER_DISABLED``).
-
-   Subsequently, calling :ref:`attached() <libs-servo-attached>` will
-   return ``NOT_ATTACHED``.
-
-.. cpp:function:: void Servo::write(unsigned int value)
-
-   If ``value`` is less than ``SERVO_MAX_WRITE_ANGLE`` (which, for
-   Arduino compatibility, is 200), it's interpreted as an angle in
-   degrees.  Otherwise, it's treated as a pulse width in microseconds.
-
-   Drives the servo to target the given angle, based on a linear
-   interpolation of the ``min`` and ``max`` pulse widths determined
-   when :ref:`attach() <libs-servo-attach>` was called.
-
-   Be aware that some (especially lower-cost) servos have fairly
-   non-linear maps between pulse width and target angle.  Make sure to
-   test your motor before relying on this method.
-
-.. cpp:function:: void Servo::writeMicroseconds(uint16 pulseWidth)
-
-   Drives the servo using a ``pulseWidth``-microsecond pulse.
-
-   If ``pulseWidth`` is outside of the [``min``, ``max``\ ] pulse
-   width range set during :ref:`attach() <libs-servo-attach>`, it will
-   be clamped to lie in this range.
-
-.. cpp:function:: int Servo::read() const
-
-   Returns the servo's target angle, in degrees.  This will be clamped
-   to lie between 0 (when the pulse width is at most ``min``) and 180
-   (when the pulse width is at least ``max``).
-
-.. cpp:function:: uint16 Servo::readMicroseconds() const
-
-   Returns the pulse width of the wave currently driving the servo, in
-   microseconds.  This will be clamped to lie in the [``min``,
-   ``max``\ ] pulse width range set during :ref:`attach()
-   <libs-servo-attach>`.
+.. doxygenclass:: Servo
+   :members:
 
 Arduino Compatibility
 ---------------------
@@ -126,9 +56,10 @@ implementation uses :ref:`timers <timers>` to drive the PWM directly.
 Consequently, **the Maple implementation only allows Servo instances
 to** :ref:`attach <libs-servo-attach>` **to pins that support PWM**.
 
-To determine if a pin supports PWM (15 Maple pins do), you can either
-check if "PWM" appears next to its number on the Maple silkscreen, or
-consult the :ref:`pwmWrite() <lang-pwmwrite>` documentation.
+To determine if a pin supports PWM, you can either check if "PWM"
+appears next to its number on your board's silkscreen, or look for it
+in the list of :ref:`boardPWMPins <lang-board-values-pwm-pins>` in
+your board's :ref:`hardware documentation <index-boards>`.
 
 RC Servos expect a pulse approximately every 20ms.  In the Maple
 implementation, :ref:`periods <lang-hardwaretimer-setperiod>` are set
@@ -141,17 +72,20 @@ which share a timer, in order to keep as many timers free for other
 purposes as possible.  Consult your board's :ref:`Timer Pin Map
 <gpio-pin-maps>` to match up pins and timer channels.
 
-Another difference: although it is not publicly documented to do so,
-the Arduino implementation of `attach()
-<http://arduino.cc/en/Reference/ServoAttach>`_ returns the timer
-channel associated with the newly-attached pin, or 0 on failure (as of
-Arduino 0021).  The Maple implementation returns :ref:`true
-<lang-constants-true>` on success, and :ref:`false
-<lang-constants-false>` on failure (and this is its documented
-behavior).
-
-We currently provide a soft (bit-banged) implementation of the
-:ref:`Wire <libs-wire>` I2C library.
+And here's some fine print:
+
+- Although it is not publicly documented to do so, the Arduino
+  implementation of `attach()
+  <http://arduino.cc/en/Reference/ServoAttach>`_ returns the timer
+  channel associated with the newly-attached pin, or 0 on failure (as
+  of Arduino 0021).  The Maple implementation returns :ref:`true
+  <lang-constants-true>` on success, and :ref:`false
+  <lang-constants-false>` on failure (and this is its documented
+  behavior).
+
+- In another bit of undocumented behavior, the Arduino implementation
+  of write() also treats its argument as an angle or a pulse width
+  depending on its value.  This is a bad idea, and we don't do it.
 
 .. rubric:: Footnotes