2 files changed, 23 insertions, 8 deletions
diff --git a/docs/source/lang/api/hardwarespi.rst b/docs/source/lang/api/hardwarespi.rst
index c71b2c3..53a225d 100644
--- a/docs/source/lang/api/hardwarespi.rst
+++ b/docs/source/lang/api/hardwarespi.rst
@@ -39,17 +39,29 @@ pins for other purposes.
 Library Documentation
 ---------------------
 
+Using the SPI Class
+^^^^^^^^^^^^^^^^^^^
+
+You can declare that you want to use SPI in your sketch by putting
+``HardwareSPI Spi(number);`` with your variables, where ``number`` is
+1 or 2, depending on which SPI you want to use.  Then you can use the
+functions described in the next section.  For example::
+
+   // Use SPI 1
+   HardwareSpi Spi(1);
+
+   void setup() {
+       Spi.begin(SPI_18MHZ);
+   }
+
+   void loop() {
+       // Get the next byte from the peripheral
+       uint8 byte = Spi.recv();
+   }
+
 HardwareSPI Class Reference
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-You can use the SPI interface by including a declaration ``HardwareSPI
-Spi(number);`` at the start of the sketch or program.  The ``number``
-must be either 1 or 2 and specifies which port to use.  Once this is
-done, you can call any of the methods documented here using
-``Spi.method(arguments)``; for example, ``Spi.send(0x13)`` would send
-the value ``0x13`` into the port buffer to be transmitted as soon as
-possible.
-
 .. cpp:class:: HardwareSPI
 
    Class for interacting with SPI.
diff --git a/docs/source/lang/api/hardwaretimer.rst b/docs/source/lang/api/hardwaretimer.rst
index 3e5424c..c7a630d 100644
--- a/docs/source/lang/api/hardwaretimer.rst
+++ b/docs/source/lang/api/hardwaretimer.rst
@@ -21,6 +21,9 @@ documented below on one of the predefined ``HardwareTimer`` instances.
 For example, to set the prescale factor on timer 1 to 5, call
 ``Timer1.setPrescaleFactor(5)``.
 
+.. TODO add code examples that people can copy and paste in case
+.. they're unfamiliar with namespace syntax
+
 .. cpp:class:: HardwareTimer
 
    Class for interacting with a timer.  There are four predefined