Docs: Various improvements.

6 files changed, 77 insertions, 58 deletions

diff --git a/docs/source/hardware/maple.rst b/docs/source/hardware/maple.rst
index e460e00..c2dc895 100644
--- a/docs/source/hardware/maple.rst
+++ b/docs/source/hardware/maple.rst
@@ -136,49 +136,54 @@ the header is connected to on the microcontroller.  The "5V?" column
 documents whether or not the pin is 5 volt tolerant.
 
 .. csv-table::
-   :header: "Pin", "STM32", ":ref:`ADC <adc>`", ":ref:`Timer <timers>`", ":ref:`I2C <i2c>`", ":ref:`UART <usart>`", ":ref:`SPI <spi>`", "5v?"
-
-   "D0",  "PA3",  "ADC3",  "TIM2_CH4",     "-",          "USART2_RX",  "-",         "No"
-   "D1",  "PA2",  "ADC2",  "TIM2_CH3",     "-",          "USART2_TX",  "-",         "No"
-   "D2",  "PA0",  "ADC0",  "TIM2_CH1_ETR", "-",          "USART2_CTS", "-",         "No"
-   "D3",  "PA1",  "ADC1",  "TIM2_CH2",     "-",          "USART2_RTS", "-",         "No"
-   "D4",  "PB5",  "-",     "-",            "ISC1_SMBA",  "-",          "-",         "No"
-   "D5",  "PB6",  "-",     "TIM4_CH1",     "I2C1_SCL",   "-",          "-",         "Yes"
-   "D6",  "PA8",  "-",     "TIM1_CH1",     "-",          "USART1_CK",  "-",         "Yes"
-   "D7",  "PA9",  "-",     "TIM1_CH2",     "-",          "USART1_TX",  "-",         "Yes"
-   "D8",  "PA10", "-",     "TIM1_CH3",     "-",          "USART1_RX",  "-",         "Yes"
-   "D9",  "PB7",  "-",     "TIM4_CH2",     "I2C1_SDA",   "-",          "-",         "Yes"
-   "D10", "PA4",  "ADC4",  "-",            "-",          "USART2_CK",  "SPI1_NSS",  "No"
-   "D11", "PA7",  "ADC7",  "TIM3_CH2",     "-",          "-",          "SPI1_MOSI", "No"
-   "D12", "PA6",  "ADC6",  "TIM3_CH1",     "-",          "-",          "SPI1_MISO", "No"
-   "D13", "PA5",  "ADC5",  "-",            "-",          "-",          "SPI1_SCK",  "No"
-   "D14", "PB8",  "-",     "TIM4_CH3",     "-",          "-",          "-",         "Yes"
-   "D15", "PC0",  "ADC10", "-",            "-",          "-",          "-",         "No"
-   "D16", "PC1",  "ADC11", "-",            "-",          "-",          "-",         "No"
-   "D17", "PC2",  "ADC12", "-",            "-",          "-",          "-",         "No"
-   "D18", "PC3",  "ADC13", "-",            "-",          "-",          "-",         "No"
-   "D19", "PC4",  "ADC14", "-",            "-",          "-",          "-",         "No"
-   "D20", "PC5",  "ADC15", "-",            "-",          "-",          "-",         "No"
-   "D21", "PC13", "-",     "-",            "-",          "-",          "-",         "No"
-   "D22", "PC14", "-",     "-",            "-",          "-",          "-",         "No"
-   "D23", "PC15", "-",     "-",            "-",          "-",          "-",         "No"
-   "D24", "PB9",  "-",     "TIM4_CH4",     "-",          "-",          "-",         "Yes"
-   "D25", "PD2",  "-",     "TIM3_ETR",     "-",          "-",          "-",         "Yes"
-   "D26", "PC10", "-",     "-",            "-",          "-",          "-",         "Yes"
-   "D27", "PB0",  "ADC8",  "TIM3_CH3",     "-",          "-",          "-",         "No"
-   "D28", "PB1",  "ADC9",  "TIM3_CH4",     "-",          "-",          "-",         "No"
-   "D29", "PB10", "-",     "-",            "I2C2_SCL",   "USART3_TX",  "-",         "Yes"
-   "D30", "PB11", "-",     "-",            "I2C2_SDA",   "USART3_RX",  "-",         "Yes"
-   "D31", "PB12", "-",     "TIM1_BKIN",    "I2C2_SMBA",  "USART3_CK",  "SPI2_NSS",  "Yes"
-   "D32", "PB13", "-",     "TIM1_CH1N",    "-",          "USART3_CTS", "SPI2_SCK",  "Yes"
-   "D33", "PB14", "-",     "TIM1_CH2N",    "-",          "USART3_RTS", "SPI2_MISO", "Yes"
-   "D34", "PB15", "-",     "TIM1_CH3N",    "-",          "-",          "SPI2_MOSI", "Yes"
-   "D35", "PC6",  "-",     "-",            "-",          "-",          "-",         "Yes"
-   "D36", "PC7",  "-",     "-",            "-",          "-",          "-",         "Yes"
-   "D37", "PC8",  "-",     "-",            "-",          "-",          "-",         "Yes"
+   :header: Pin, STM32, :ref:`ADC <adc>`, :ref:`Timer <timers>`, :ref:`I2C <i2c>`, :ref:`UART <usart>`, :ref:`SPI <spi>`, 5v?
+
+   D0,  PA3,  ADC3,  TIM2_CH4,     -,          USART2_RX,  -,         No
+   D1,  PA2,  ADC2,  TIM2_CH3,     -,          USART2_TX,  -,         No
+   D2,  PA0,  ADC0,  TIM2_CH1_ETR, -,          USART2_CTS, -,         No
+   D3,  PA1,  ADC1,  TIM2_CH2,     -,          USART2_RTS, -,         No
+   D4,  PB5,  -,     -,            ISC1_SMBA,  -,          -,         No
+   D5,  PB6,  -,     TIM4_CH1,     I2C1_SCL,   -,          -,         Yes
+   D6,  PA8,  -,     TIM1_CH1,     -,          USART1_CK,  -,         Yes
+   D7,  PA9,  -,     TIM1_CH2,     -,          USART1_TX,  -,         Yes
+   D8,  PA10, -,     TIM1_CH3,     -,          USART1_RX,  -,         Yes
+   D9,  PB7,  -,     TIM4_CH2,     I2C1_SDA,   -,          -,         Yes
+   D10, PA4,  ADC4,  -,            -,          USART2_CK,  SPI1_NSS,  No
+   D11, PA7,  ADC7,  TIM3_CH2,     -,          -,          SPI1_MOSI, No
+   D12, PA6,  ADC6,  TIM3_CH1,     -,          -,          SPI1_MISO, No
+   D13, PA5,  ADC5,  -,            -,          -,          SPI1_SCK,  No
+   D14, PB8,  -,     TIM4_CH3,     -,          -,          -,         Yes
+   D15, PC0,  ADC10, -,            -,          -,          -,         No
+   D16, PC1,  ADC11, -,            -,          -,          -,         No
+   D17, PC2,  ADC12, -,            -,          -,          -,         No
+   D18, PC3,  ADC13, -,            -,          -,          -,         No
+   D19, PC4,  ADC14, -,            -,          -,          -,         No
+   D20, PC5,  ADC15, -,            -,          -,          -,         No
+   D21, PC13, -,     -,            -,          -,          -,         No
+   D22, PC14, -,     -,            -,          -,          -,         No
+   D23, PC15, -,     -,            -,          -,          -,         No
+   D24, PB9,  -,     TIM4_CH4,     -,          -,          -,         Yes
+   D25, PD2,  -,     TIM3_ETR,     -,          -,          -,         Yes
+   D26, PC10, -,     -,            -,          -,          -,         Yes
+   D27, PB0,  ADC8,  TIM3_CH3,     -,          -,          -,         No
+   D28, PB1,  ADC9,  TIM3_CH4,     -,          -,          -,         No
+   D29, PB10, -,     -,            I2C2_SCL,   USART3_TX,  -,         Yes
+   D30, PB11, -,     -,            I2C2_SDA,   USART3_RX,  -,         Yes
+   D31, PB12, -,     TIM1_BKIN,    I2C2_SMBA,  USART3_CK,  SPI2_NSS,  Yes
+   D32, PB13, -,     TIM1_CH1N,    -,          USART3_CTS, SPI2_SCK,  Yes
+   D33, PB14, -,     TIM1_CH2N,    -,          USART3_RTS, SPI2_MISO, Yes
+   D34, PB15, -,     TIM1_CH3N,    -,          -,          SPI2_MOSI, Yes
+   D35, PC6,  -,     -,            -,          -,          -,         Yes
+   D36, PC7,  -,     -,            -,          -,          -,         Yes
+   D37, PC8,  -,     -,            -,          -,          -,         Yes
 
 .. TODO [0.0.10] JTAG pins
 
+.. The following pins are used for :ref:`jtag` debugging by default, but
+.. can be used as ordinary GPIOs through the use of the
+.. :ref:`lang-disabledebugports` function.  (Though see :ref:`this
+.. erratum <maple-reset-njtrst>`).
+
 Timer Pin Map
 ^^^^^^^^^^^^^
 
@@ -353,6 +358,8 @@ Rev 5
   from its silkscreen.  This mistake was fixed in later manufacturing
   runs.
 
+.. _maple-reset-njtrst:
+
 * **Reset and NJTRST tied together**: The MCU's reset pin is connected
   to PB4, the NJTRST pin, which is pin 43.  Thus, attempting to use
   pin 43 as a GPIO will reset your board (and also prevents the JTAG
diff --git a/docs/source/i2c.rst b/docs/source/i2c.rst
index e3d68c0..31976ac 100644
--- a/docs/source/i2c.rst
+++ b/docs/source/i2c.rst
@@ -25,7 +25,7 @@ interrupt handlers) at the same time.
 Hardware/Circuit Design
 -----------------------
 
-.. FIXME [0.0.10 add links to board-specific values]
+.. FIXME [0.1.0] Link to board-specific values (BOARD_I2C1_SDA_PIN, etc.)
 
 Maple boards have two |i2c| ports.  Maples reliably communicate with
 up to a 400kHz clock speed; this doesn't translate into a 400kbps data
diff --git a/docs/source/index.rst b/docs/source/index.rst
index f6b7f92..ce3985f 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -54,6 +54,7 @@ Have fun!
    pwm
    spi
    timers
+   systick
    usb
    usart
 
diff --git a/docs/source/libmaple/api/systick.rst b/docs/source/libmaple/api/systick.rst
index a02b8e4..a8c0971 100644
--- a/docs/source/libmaple/api/systick.rst
+++ b/docs/source/libmaple/api/systick.rst
@@ -1,14 +1,13 @@
 .. highlight:: c
 
-
-.. _libmaple-systick:
-
 .. FIXME [0.0.10] move these to the right places:
 
 .. _libmaple-systick_disable:
 
 .. _libmaple-systick_resume:
 
+.. _libmaple-systick:
+
 ``systick.h``
 =============
 
diff --git a/docs/source/systick.rst b/docs/source/systick.rst
new file mode 100644
index 0000000..6f20133
--- /dev/null
+++ b/docs/source/systick.rst
@@ -0,0 +1,13 @@
+SysTick
+=======
+
+.. TODO Recommended reading and more content.
+
+The SysTick peripheral provides a timer which :ref:`libmaple` uses to
+keep track of the board's uptime.
+
+Library Documentation
+---------------------
+
+See :ref:`libmaple-systick` for more information on library support
+for interfacing with the SysTick peripheral.
diff --git a/docs/source/timers.rst b/docs/source/timers.rst
index 9163e69..403193f 100644
--- a/docs/source/timers.rst
+++ b/docs/source/timers.rst
@@ -5,8 +5,6 @@
 Timers
 ======
 
-.. FIXME [0.0.10] links to systick.h in a few places on this page
-
 There are four general purpose timers in the Maple microcontroller
 that can be configured to generate periodic or delayed events with
 minimal work done by the microcontroller. For example, the :ref:`PWM
@@ -55,10 +53,11 @@ events to be programmed at 4 different rates on a single timer.  Note
 that function call overheads mean that the smallest increment rate is
 at least a few microseconds.
 
-Function Reference
-------------------
+Library Documentation
+---------------------
 
-* :ref:`HardwareTimer <lang-hardwaretimer>`
+See the :ref:`HardwareTimer <lang-hardwaretimer>` reference for more
+information on controlling the built-in timers.
 
 Caveats
 -------
@@ -109,12 +108,12 @@ you put your Maple into :ref:`perpetual bootloader mode
 to it (or somehow causing your program to re-enable serial over USB
 using :ref:`SerialUSB.begin() <lang-serialusb-begin>`).
 
-The SysTick peripheral another way to perform periodic or delayed
-events.  Its separate timer does not conflict with any other
-peripherals, but the associated 1 kHz interrupt can jitter the general
-purpose timer interrupts.  The SysTick peripheral can be disabled by
-calling :ref:`systick_disable() <libmaple-systick_disable>`, and
-re-enabled using :ref:`systick_resume() <libmaple-systick_resume>`.
-However, be aware that calling ``systick_disable()`` will stop the
-values coming from :ref:`lang-micros` and :ref:`lang-millis` from
-increasing.
+The :ref:`SysTick <systick>` peripheral another way to perform
+periodic or delayed events.  Its separate timer does not conflict with
+any other peripherals, but the associated 1 kHz interrupt can jitter
+the general purpose timer interrupts.  The SysTick peripheral can be
+disabled by calling :ref:`systick_disable()
+<libmaple-systick_disable>`, and re-enabled using
+:ref:`systick_resume() <libmaple-systick_resume>`.  However, be aware
+that calling ``systick_disable()`` will stop the values coming from
+:ref:`lang-micros` and :ref:`lang-millis` from increasing.