Doxygen hacks and fixups.

- Shut Doxygen up in various places
- Fix some genuine docs bugs
- Ignore sources we're not responsible for

Signed-off-by: Marti Bolivar <mbolivar@leaflabs.com>

10 files changed, 24 insertions, 25 deletions

diff --git a/libmaple/include/libmaple/dma.h b/libmaple/include/libmaple/dma.h
index 0b1ec4c..e22cdaf 100644
--- a/libmaple/include/libmaple/dma.h
+++ b/libmaple/include/libmaple/dma.h
@@ -294,7 +294,7 @@ extern void dma_set_mem_addr(dma_dev *dev, dma_tube tube, __io void *address);
  *
  * @param dev DMA Device
  * @param tube Tube whose peripheral data register base address to set.
- * @param addr Peripheral memory base address to use.
+ * @param address Peripheral memory base address to use.
  */
 extern void dma_set_per_addr(dma_dev *dev, dma_tube tube, __io void *address);
 
diff --git a/libmaple/include/libmaple/dma_common.h b/libmaple/include/libmaple/dma_common.h
index 67475f7..3765cd5 100644
--- a/libmaple/include/libmaple/dma_common.h
+++ b/libmaple/include/libmaple/dma_common.h
@@ -29,11 +29,9 @@
  * @author Marti Bolivar <mbolivar@leaflabs.com>
  * @brief Common DMA sub-header for <series/dma.h> and <libmaple/dma.h>.
  *
- * WARNING: CONTENTS UNSTABLE
- *
- * The existence of this file is an implementation detail.  Its
- * contents are not stable, so never include it directly.  If you need
- * something from here, #include <libmaple/dma.h> instead.
+ * CONTENTS UNSTABLE. The existence of this file is an implementation
+ * detail.  Never include it directly.  If you need something from
+ * here, include <libmaple/dma.h> instead.
  */
 
 /*
diff --git a/libmaple/include/libmaple/i2c_common.h b/libmaple/include/libmaple/i2c_common.h
index 5d99530..17cabe3 100644
--- a/libmaple/include/libmaple/i2c_common.h
+++ b/libmaple/include/libmaple/i2c_common.h
@@ -30,11 +30,9 @@
  * @author Marti Bolivar <mbolivar@leaflabs.com>
  * @brief This file is an implementation detail
  *
- * WARNING: CONTENTS UNSTABLE
- *
- * The existence of this file is an implementation detail.  Its
- * contents are not stable, so never include it directly.  If you need
- * something from here, #include <libmaple/i2c.h> instead.
+ * CONTENTS UNSTABLE. The existence of this file is an implementation
+ * detail.  Never include it directly.  If you need something from
+ * here, include <libmaple/i2c.h> instead.
  */
 
 #ifndef _LIBMAPLE_I2C_COMMON_H_
diff --git a/libmaple/include/libmaple/spi.h b/libmaple/include/libmaple/spi.h
index fab643f..4acd230 100644
--- a/libmaple/include/libmaple/spi.h
+++ b/libmaple/include/libmaple/spi.h
@@ -215,11 +215,12 @@ void spi_init(spi_dev *dev);
 struct gpio_dev;
 /**
  * @brief Configure GPIO bit modes for use as a SPI port's pins.
- * @param as_master If true, configure bits for use as a bus master.
- *                  Otherwise, configure bits for use as slave.
+ *
+ * @param dev SPI device
+ * @param as_master If true, configure as bus master; otherwise, as slave.
  * @param nss_dev NSS pin's GPIO device
- * @param comm_dev SCK, MISO, MOSI pins' GPIO device
  * @param nss_bit NSS pin's GPIO bit on nss_dev
+ * @param comm_dev SCK, MISO, MOSI pins' GPIO device
  * @param sck_bit SCK pin's GPIO bit on comm_dev
  * @param miso_bit MISO pin's GPIO bit on comm_dev
  * @param mosi_bit MOSI pin's GPIO bit on comm_dev
diff --git a/libmaple/stm32f1/include/series/i2c.h b/libmaple/stm32f1/include/series/i2c.h
index a0822e8..f407955 100644
--- a/libmaple/stm32f1/include/series/i2c.h
+++ b/libmaple/stm32f1/include/series/i2c.h
@@ -26,7 +26,7 @@
  *****************************************************************************/
 
 /**
- * @file libmaple/include/stm32f1/include/series/i2c.h
+ * @file libmaple/stm32f1/include/series/i2c.h
  * @brief STM32F1 I2C
  */
 
diff --git a/libmaple/stm32f2/include/series/gpio.h b/libmaple/stm32f2/include/series/gpio.h
index 1496e8e..4d0d98c 100644
--- a/libmaple/stm32f2/include/series/gpio.h
+++ b/libmaple/stm32f2/include/series/gpio.h
@@ -222,7 +222,7 @@ void gpio_set_modef(struct gpio_dev *dev,
  * default speed.
  *
  * @param dev GPIO device.
- * @param pin Pin on the device whose mode to set, 0--15.
+ * @param bit Bit on the device whose mode to set, 0--15.
  * @param mode Mode to set the pin to.
  */
 static inline void gpio_set_mode(struct gpio_dev *dev,
diff --git a/libmaple/usb/stm32f1/usb.c b/libmaple/usb/stm32f1/usb.c
index 0130bab..c20cc71 100644
--- a/libmaple/usb/stm32f1/usb.c
+++ b/libmaple/usb/stm32f1/usb.c
@@ -25,7 +25,7 @@
  *****************************************************************************/
 
 /**
- * @file libmaple/usb/usb.c
+ * @file libmaple/usb/stm32f1/usb.c
  * @brief USB support.
  *
  * This is a mess. What we need almost amounts to a ground-up rewrite.
diff --git a/libmaple/usb/stm32f1/usb_cdcacm.c b/libmaple/usb/stm32f1/usb_cdcacm.c
index 6ef4806..6a8235e 100644
--- a/libmaple/usb/stm32f1/usb_cdcacm.c
+++ b/libmaple/usb/stm32f1/usb_cdcacm.c
@@ -25,7 +25,7 @@
  *****************************************************************************/
 
 /**
- * @file libmaple/usb/usb_cdcacm.c
+ * @file libmaple/usb/stm32f1/usb_cdcacm.c
  * @brief USB CDC ACM (a.k.a. virtual serial terminal, VCOM).
  *
  * FIXME: this works on the STM32F1 USB peripherals, and probably no
diff --git a/support/doxygen/Doxyfile b/support/doxygen/Doxyfile
index daeaf38..170cff4 100644
--- a/support/doxygen/Doxyfile
+++ b/support/doxygen/Doxyfile
@@ -564,7 +564,7 @@ WARN_IF_DOC_ERROR      = YES
 # wrong or incomplete parameter documentation, but not about the absence of 
 # documentation.
 
-WARN_NO_PARAMDOC       = YES
+WARN_NO_PARAMDOC       = NO
 
 # The WARN_FORMAT tag determines the format of the warning messages that 
 # doxygen can produce. The string should contain the $file, $line, and $text 
@@ -621,9 +621,8 @@ RECURSIVE              = YES
 # excluded from the INPUT source files. This way you can easily exclude a 
 # subdirectory from a directory tree whose root is specified with the INPUT tag.
 
-# FIXME The USB thing needs to get redone (ST code stripped out,
-# etc.).  Until then, just ignore it.
-EXCLUDE                = ../libmaple/usb/
+# We include the FreeRTOS sources. That's probably a mistake. Oh well.
+EXCLUDE                = ./libraries/FreeRTOS/
 
 # The EXCLUDE_SYMLINKS tag can be used select whether or not files or 
 # directories that are symbolic links (a Unix filesystem feature) are excluded 
@@ -1351,13 +1350,13 @@ EXPAND_ONLY_PREDEF     = YES
 # If the SEARCH_INCLUDES tag is set to YES (the default) the includes files 
 # in the INCLUDE_PATH (see below) will be search if a #include is found.
 
-SEARCH_INCLUDES        = YES
+SEARCH_INCLUDES        = NO
 
 # The INCLUDE_PATH tag can be used to specify one or more directories that 
 # contain include files that are not input files but should be processed by 
 # the preprocessor.
 
-INCLUDE_PATH           = 
+INCLUDE_PATH           =
 
 # You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard 
 # patterns (like *.h and *.hpp) to filter out the header-files in the 
@@ -1383,6 +1382,9 @@ PREDEFINED             = __attribute__()= \
                        STM32_MEDIUM_DENSITY \
                        STM32_HIGH_DENSITY \
                        STM32_XL_DENSITY \
+                       PCLK1=0 STM32_PCLK1=0 \
+                       PCLK2=0 STM32_PCLK2=0 \
+                       STM32_HAVE_TIMER(x)=1 \
                        __DOXYGEN__
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then 
diff --git a/wirish/boards/maple_native/include/board/board.h b/wirish/boards/maple_native/include/board/board.h
index 397afaf..f8ffd86 100644
--- a/wirish/boards/maple_native/include/board/board.h
+++ b/wirish/boards/maple_native/include/board/board.h
@@ -25,7 +25,7 @@
  *****************************************************************************/
 
 /**
- * @file   wirish/boards/maple_native/include/board/board.h.
+ * @file   wirish/boards/maple_native/include/board/board.h
  * @author Marti Bolivar <mbolivar@leaflabs.com>
  * @brief  Maple Native board header file.
  *