Merge remote branch 'nzmichaelh/comment-fixups-2'

15 files changed, 68 insertions, 4 deletions

diff --git a/libmaple/bkp.c b/libmaple/bkp.c
index 00a2833..7d1ad7f 100644
--- a/libmaple/bkp.c
+++ b/libmaple/bkp.c
@@ -24,6 +24,11 @@
  * SOFTWARE.
  *****************************************************************************/
 
+/**
+ * @file bkp.c
+ * @brief Backup register support.
+ */
+
 #include "bkp.h"
 #include "pwr.h"
 #include "rcc.h"
diff --git a/libmaple/dac.c b/libmaple/dac.c
index 4070984..15e944f 100644
--- a/libmaple/dac.c
+++ b/libmaple/dac.c
@@ -24,6 +24,11 @@
  * SOFTWARE.
  *****************************************************************************/
 
+/**
+ * @file dac.c
+ * @brief Digital to analog converter support.
+ */
+
 #include "libmaple.h"
 #include "gpio.h"
 #include "dac.h"
diff --git a/libmaple/dac.h b/libmaple/dac.h
index db0fae7..aa04981 100644
--- a/libmaple/dac.h
+++ b/libmaple/dac.h
@@ -26,7 +26,7 @@
 
 /**
  * @file dac.h
- * @brief Digital to analog converter header file
+ * @brief Digital to analog converter support.
  */
 
 /* See notes/dac.txt for more info */
diff --git a/libmaple/fsmc.c b/libmaple/fsmc.c
index 68890c9..06ca7df 100644
--- a/libmaple/fsmc.c
+++ b/libmaple/fsmc.c
@@ -25,7 +25,8 @@
  *****************************************************************************/
 
 /**
- * @brief
+ * @file fsmc.c
+ * @brief Flexible static memory controller support.
  */
 
 #include "fsmc.h"
diff --git a/libmaple/fsmc.h b/libmaple/fsmc.h
index f9529cd..ef82b08 100644
--- a/libmaple/fsmc.h
+++ b/libmaple/fsmc.h
@@ -24,6 +24,11 @@
  * SOFTWARE.
  *****************************************************************************/
 
+/**
+ * @file fsmc.h
+ * @brief Flexible static memory controller support.
+ */
+
 /*
  * See ../notes/fsmc.txt for more info
  */
diff --git a/libmaple/gpio.c b/libmaple/gpio.c
index 0984aab..e643873 100644
--- a/libmaple/gpio.c
+++ b/libmaple/gpio.c
@@ -25,6 +25,7 @@
  *****************************************************************************/
 
 /**
+ * @file gpio.c
  * @brief GPIO initialization routine
  */
 
diff --git a/libmaple/nvic.c b/libmaple/nvic.c
index bbbf13f..3be5a5a 100644
--- a/libmaple/nvic.c
+++ b/libmaple/nvic.c
@@ -25,7 +25,8 @@
  *****************************************************************************/
 
 /**
- * @brief Nested interrupt controller routines
+ * @file nvic.c
+ * @brief Nested vector interrupt controller support.
  */
 
 #include "nvic.h"
diff --git a/libmaple/nvic.h b/libmaple/nvic.h
index 1630bc1..e3b052d 100644
--- a/libmaple/nvic.h
+++ b/libmaple/nvic.h
@@ -27,6 +27,20 @@
 /**
  * @file nvic.h
  * @brief Nested vector interrupt controller support.
+ *
+ * Basic usage:
+ *
+ * @code
+ *   // Initialise the interrupt controller and point to the vector
+ *   // table at the start of flash.
+ *   nvic_init(0x08000000, 0);
+ *   // Bind in a timer interrupt handler
+ *   timer_attach_interrupt(TIMER_CC1_INTERRUPT, handler);
+ *   // Optionally set the priority
+ *   nvic_irq_set_priority(NVIC_TIMER1_CC, 5);
+ *   // All done, enable all interrupts
+ *   nvic_globalirq_enable();
+ * @endcode
  */
 
 #ifndef _NVIC_H_
@@ -146,8 +160,22 @@ typedef enum nvic_irq_num {
 #endif
 } nvic_irq_num;
 
+/*
+ * Initialises the interrupt controller and sets all interrupts to the
+ * lowest priority.
+ *
+ * For stand-alone products, the base address is normally the start of
+ * flash (0x08000000).
+ *
+ * @param vector_table_address  base address of the vector table
+ */
 void nvic_init(uint32 vector_table_address, uint32 offset);
+
+/**
+ * Sets the base address of the vector table.
+ */
 void nvic_set_vector_table(uint32 address, uint32 offset);
+
 void nvic_irq_set_priority(nvic_irq_num irqn, uint8 priority);
 
 /**
diff --git a/libmaple/pwr.c b/libmaple/pwr.c
index 83d289d..ead8b64 100644
--- a/libmaple/pwr.c
+++ b/libmaple/pwr.c
@@ -24,6 +24,11 @@
  * SOFTWARE.
  *****************************************************************************/
 
+/**
+ * @file pwr.c
+ * @brief Power control (PWR) support.
+ */
+
 #include "pwr.h"
 #include "rcc.h"
 
diff --git a/libmaple/rcc.c b/libmaple/rcc.c
index 9267972..f3018ee 100644
--- a/libmaple/rcc.c
+++ b/libmaple/rcc.c
@@ -25,6 +25,7 @@
  *****************************************************************************/
 
 /**
+ * @file rcc.c
  * @brief Implements pretty much only the basic clock setup on the
  *        stm32, clock enable/disable and peripheral reset commands.
  */
diff --git a/libmaple/syscalls.c b/libmaple/syscalls.c
index 9193a17..8a57945 100644
--- a/libmaple/syscalls.c
+++ b/libmaple/syscalls.c
@@ -24,6 +24,12 @@
  * SOFTWARE.
  *****************************************************************************/
 
+/**
+ * @file syscalls.c
+ * @brief Low level system routines used by Newlib for basic I/O and
+ * memory allocation.
+ */
+
 #include "libmaple.h"
 
 #include <sys/stat.h>
diff --git a/libmaple/systick.c b/libmaple/systick.c
index 1eb2117..9bb5d50 100644
--- a/libmaple/systick.c
+++ b/libmaple/systick.c
@@ -25,6 +25,7 @@
  *****************************************************************************/
 
 /**
+ * @file systick.c
  * @brief System timer interrupt handler and initialization routines
  */
 
diff --git a/libmaple/timer.h b/libmaple/timer.h
index f142908..dfc8a4f 100644
--- a/libmaple/timer.h
+++ b/libmaple/timer.h
@@ -659,7 +659,8 @@ static inline uint16 timer_get_prescaler(timer_dev *dev) {
 /**
  * @brief Set a timer's prescale value.
  *
- * The new value will not take effect until the next update event.
+ * Divides the input clock by (PSC+1).  The new value will not take
+ * effect until the next update event.
  *
  * @param dev Timer whose prescaler to set
  * @param psc New prescaler value
diff --git a/libmaple/util.c b/libmaple/util.c
index bb56a62..eead625 100644
--- a/libmaple/util.c
+++ b/libmaple/util.c
@@ -25,6 +25,7 @@
  *****************************************************************************/
 
 /**
+ * @file util.c
  * @brief Utility procedures for debugging, mostly an error LED fade
  * and messages dumped over a UART for failed asserts.
  */
diff --git a/libmaple/util.h b/libmaple/util.h
index 080f1bf..7b41769 100644
--- a/libmaple/util.h
+++ b/libmaple/util.h
@@ -42,10 +42,13 @@ extern "C"{
  * Bit manipulation
  */
 
+/** 1 << the bit number */
 #define BIT(shift)                     (1UL << (shift))
+/** Mask shifted left by 'shift' */
 #define BIT_MASK_SHIFT(mask, shift)    ((mask) << (shift))
 /** Bits m to n of x */
 #define GET_BITS(x, m, n) ((((uint32)x) << (31 - (n))) >> ((31 - (n)) + (m)))
+/** True if v is a power of two (1, 2, 4, 8, ...) */
 #define IS_POWER_OF_TWO(v)  ((v) && !((v) & ((v) - 1)))
 
 /*