Finalized 0.0.9 documentation.

6 files changed, 62 insertions, 43 deletions

diff --git a/wirish/HardwareTimer.cpp b/wirish/HardwareTimer.cpp
index 92c6adf..354663e 100644
--- a/wirish/HardwareTimer.cpp
+++ b/wirish/HardwareTimer.cpp
@@ -221,7 +221,6 @@ HardwareTimer* getTimer(timer_dev_num timerNum) {
         return &Timer8;
 #endif
     default:
-        ASSERT(0);
         return 0;
     }
 }
diff --git a/wirish/HardwareTimer.h b/wirish/HardwareTimer.h
index c72175f..4034b1f 100644
--- a/wirish/HardwareTimer.h
+++ b/wirish/HardwareTimer.h
@@ -89,7 +89,7 @@ class HardwareTimer {
      *
      * Note that there is some function call overhead associated with
      * using this method, so using it in concert with
-     * HardwareTimer::resume() is not a robust way to align multiple
+     * HardwareTimer::pause() is not a robust way to align multiple
      * timers to the same count value.
      *
      * @see HardwareTimer::pause()
@@ -103,7 +103,7 @@ class HardwareTimer {
     uint16 getPrescaleFactor();
 
     /**
-     * Set the timer prescale.
+     * Set the timer's prescale factor.
      *
      * The prescaler acts as a clock divider to slow down the rate at
      * which the counter increments.
@@ -155,7 +155,7 @@ class HardwareTimer {
      * Set the current timer count.
      *
      * Note that there is some function call overhead associated with
-     * callign this method, so using it is not a robust way to get
+     * calling this method, so using it is not a robust way to get
      * multiple timers to share a count value.
      *
      * @param val The new count value to set.  If this value exceeds
@@ -184,10 +184,6 @@ class HardwareTimer {
     /**
      * Set the given channel of this timer to the given mode.
      *
-     * Note: Timer1.setChannel1Mode(TIMER_PWM) may not work as
-     * expected; if you want PWM functionality on a channel make sure
-     * you don't set it to something else!
-     *
      * @param channel Timer channel, from 1 to 4
      * @param mode Mode to set
      */
@@ -228,24 +224,24 @@ class HardwareTimer {
      */
     uint16 getCompare(int channel);
 
-    /** Like getCompare(1) */
+    /** Equivalent to getCompare(1) */
     uint16 getCompare1();
 
-    /** Like getCompare(2) */
+    /** Equivalent to getCompare(2) */
     uint16 getCompare2();
 
-    /** Like getCompare(3) */
+    /** Equivalent to getCompare(3) */
     uint16 getCompare3();
 
-    /** Like getCompare(4) */
+    /** Equivalent to getCompare(4) */
     uint16 getCompare4();
 
     /**
      * Sets the compare value for the given channel.
      *
      * When the counter reaches this value the interrupt for this
-     * channel will fire if channel 1 mode is TIMER_OUTPUTCOMPARE and
-     * an interrupt is attached.
+     * channel will fire if the channel mode is TIMER_OUTPUTCOMPARE
+     * and an interrupt is attached.
      *
      * By default, this only changes the relative offsets between
      * events on a single timer ("phase"); they don't control the
@@ -259,32 +255,33 @@ class HardwareTimer {
      * few microseconds.
      *
      * @param channel the channel whose compare to set, from 1 to 4.
-     * @param val The compare value to set.  If greater than this
-     *            timer's overflow value, it will be truncated to the
-     *            overflow value.
+     * @param compare The compare value to set.  If greater than this
+     *                timer's overflow value, it will be truncated to
+     *                the overflow value.
      *
      * @see TimerMode
      * @see HardwareTimer::setChannelMode()
+     * @see HardwareTimer::attachInterrupt()
      */
     void setCompare(int channel, uint16 compare);
 
     /**
-     * Like setCompare(1, compare).
+     * Equivalent to setCompare(1, compare).
      */
     void setCompare1(uint16 compare);
 
     /**
-     * Like setCompare(2, compare).
+     * Equivalent to setCompare(2, compare).
      */
     void setCompare2(uint16 compare);
 
     /**
-     * Like setCompare(3, compare).
+     * Equivalent to setCompare(3, compare).
      */
     void setCompare3(uint16 compare);
 
     /**
-     * Like setCompare(4, compare).
+     * Equivalent to setCompare(4, compare).
      */
     void setCompare4(uint16 compare);
 
@@ -313,25 +310,25 @@ class HardwareTimer {
     void attachInterrupt(int channel, voidFuncPtr handler);
 
     /**
-     * Like attachCompareInterrupt(1, handler).
+     * Equivalent to attachCompareInterrupt(1, handler).
      * @see HardwareTimer::attachCompareInterrupt()
      */
     void attachCompare1Interrupt(voidFuncPtr handler);
 
     /**
-     * Like attachCompareInterrupt(2, handler).
+     * Equivalent to attachCompareInterrupt(2, handler).
      * @see HardwareTimer::attachCompareInterrupt()
      */
     void attachCompare2Interrupt(voidFuncPtr handler);
 
     /**
-     * Like attachCompareInterrupt(3, handler).
+     * Equivalent to attachCompareInterrupt(3, handler).
      * @see HardwareTimer::attachCompareInterrupt()
      */
     void attachCompare3Interrupt(voidFuncPtr handler);
 
     /**
-     * Like attachCompareInterrupt(4, handler).
+     * Equivalent to attachCompareInterrupt(4, handler).
      * @see HardwareTimer::attachCompareInterrupt()
      */
     void attachCompare4Interrupt(voidFuncPtr handler);
@@ -346,25 +343,25 @@ class HardwareTimer {
     void detachInterrupt(int channel);
 
     /**
-     * Like detachInterrupt(1).
+     * Equivalent to detachInterrupt(1).
      * @see HardwareTimer::detachInterrupt()
      */
     void detachCompare1Interrupt(void);
 
     /**
-     * Like detachInterrupt(2).
+     * Equivalent to detachInterrupt(2).
      * @see HardwareTimer::detachInterrupt()
      */
     void detachCompare2Interrupt(void);
 
     /**
-     * Like detachInterrupt(3).
+     * Equivalent to detachInterrupt(3).
      * @see HardwareTimer::detachInterrupt()
      */
     void detachCompare3Interrupt(void);
 
     /**
-     * Like detachInterrupt(4).
+     * Equivalent to detachInterrupt(4).
      * @see HardwareTimer::detachInterrupt()
      */
     void detachCompare4Interrupt(void);
@@ -394,6 +391,22 @@ extern HardwareTimer Timer5;
 extern HardwareTimer Timer8;
 #endif
 
+/**
+ * Get one of the pre-instantiated HardwareTimer instances, given a
+ * timer device number.
+ *
+ * Be careful not to pass an actual number to this function.  For
+ * example, getTimer(1) will not return Timer1.  Use a real
+ * timer_dev_num, e.g. TIMER1, TIMER2, etc.
+ *
+ * @param timerNum the timer device number, e.g. TIMER1.
+ *
+ * @return Pointer to the HardwareTimer instance corresponding to the
+ * given timer device number.  If timerNum is TIMER_INVALID, returns a
+ * null pointer.
+ *
+ * @see timer_dev_num
+ */
 HardwareTimer* getTimer(timer_dev_num timerNum);
 
 #endif
diff --git a/wirish/comm/HardwareSPI.h b/wirish/comm/HardwareSPI.h
index 03d1ea1..7241d0b 100644
--- a/wirish/comm/HardwareSPI.h
+++ b/wirish/comm/HardwareSPI.h
@@ -29,18 +29,23 @@
 #ifndef _HARDWARESPI_H_
 #define _HARDWARESPI_H_
 
+/**
+ * Defines the possible SPI communication speeds.
+ */
 typedef enum SPIFrequency {
-    SPI_18MHZ       = 0,
-    SPI_9MHZ        = 1,
-    SPI_4_5MHZ      = 2,
-    SPI_2_25MHZ     = 3,
-    SPI_1_125MHZ    = 4,
-    SPI_562_500KHZ  = 5,
-    SPI_281_250KHZ  = 6,
-    SPI_140_625KHZ  = 7,
-    MAX_SPI_FREQS   = 8,
+    SPI_18MHZ       = 0, /**< 18 MHz */
+    SPI_9MHZ        = 1, /**< 9 MHz */
+    SPI_4_5MHZ      = 2, /**< 4.5 MHz */
+    SPI_2_25MHZ     = 3, /**< 2.25 MHZ */
+    SPI_1_125MHZ    = 4, /**< 1.125 MHz */
+    SPI_562_500KHZ  = 5, /**< 562.500 KHz */
+    SPI_281_250KHZ  = 6, /**< 281.250 KHz */
+    SPI_140_625KHZ  = 7, /**< 140.625 KHz */
+    MAX_SPI_FREQS   = 8, /**< The number of SPI frequencies. */
 } SPIFrequency;
 
+/* Documented by hand in docs/source/lang/api/hardwarespi.rst; if you
+   make any changes, make sure to update this document. */
 class HardwareSPI {
  private:
     uint32 spi_num;
diff --git a/wirish/ext_interrupts.h b/wirish/ext_interrupts.h
index 057c0d3..304e267 100644
--- a/wirish/ext_interrupts.h
+++ b/wirish/ext_interrupts.h
@@ -86,7 +86,7 @@ void detachInterrupt(uint8 pin);
  *
  * @see noInterrupts()
  */
-static inline __attribute__((always_inline)) void interrupts() {
+static ALWAYS_INLINE void interrupts() {
     nvic_globalirq_enable();
 }
 
@@ -100,7 +100,7 @@ static inline __attribute__((always_inline)) void interrupts() {
  *
  * @see interrupts()
  */
-static inline __attribute__((always_inline)) void noInterrupts() {
+static ALWAYS_INLINE void noInterrupts() {
     nvic_globalirq_disable();
 }
 
diff --git a/wirish/io.h b/wirish/io.h
index 547dc8e..2d22dcd 100644
--- a/wirish/io.h
+++ b/wirish/io.h
@@ -145,7 +145,7 @@ void digitalWrite(uint8 pin, uint8 value);
  * @return LOW or HIGH.
  * @see pinMode()
  */
-uint32 digitalRead(uint8);
+uint32 digitalRead(uint8 pin);
 
 /**
  * Read an analog value from pin.  This function blocks during ADC
diff --git a/wirish/wirish_math.h b/wirish/wirish_math.h
index 4156722..14614ba 100644
--- a/wirish/wirish_math.h
+++ b/wirish/wirish_math.h
@@ -79,8 +79,10 @@ long random(long min, long max);
  * @return the mapped value.
  */
 /* TODO: profile code bloat due to inlining this */
-inline long map(long x, long in_min, long in_max, long out_min, long out_max) {
-    return (x - in_min) * (out_max - out_min) / (in_max - in_min) + out_min;
+inline long map(long value, long fromStart, long fromEnd,
+                long toStart, long toEnd) {
+    return (value - fromStart) * (toEnd - toStart) / (fromEnd - fromStart) +
+        toStart;
 }
 
 #define PI          3.1415926535897932384626433832795