From c1eeb55551461efb365bed546666fbf843e0e7bf Mon Sep 17 00:00:00 2001
From: Marti Bolivar <mbolivar@leaflabs.com>
Date: Mon, 22 Aug 2011 22:38:13 -0400
Subject: stm32.h: Doxygen

---
 libmaple/stm32.h | 69 ++++++++++++++++++++++++++++++++++++++++----------------
 1 file changed, 49 insertions(+), 20 deletions(-)

(limited to 'libmaple')

diff --git a/libmaple/stm32.h b/libmaple/stm32.h
index 6cf5ba4..0d19ddb 100644
--- a/libmaple/stm32.h
+++ b/libmaple/stm32.h
@@ -32,6 +32,14 @@
 #ifndef _STM32_H_
 #define _STM32_H_
 
+/*
+ * User-specific configuration.
+ *
+ * The #defines here depend upon how libmaple is used.  Because of the
+ * potential for a mismatch between them and the actual libmaple
+ * usage, you should try to keep their number to an absolute minimum.
+ */
+
 /**
  * \def PCLK1
  * Clock speed of APB1 peripherals, in Hz.
@@ -49,9 +57,17 @@
 #define PCLK2   72000000U
 #endif
 
+/*
+ * Density-specific configuration.
+ */
+
 /**
  * \def NR_INTERRUPTS
- * Number of interrupts in the NVIC.
+ *
+ * Number of interrupts in the NVIC.  This define is automatically
+ * generated whenever the proper density is defined (currently, this
+ * is restricted to defining one of STM32_MEDIUM_DENSITY and
+ * STM32_HIGH_DENSITY).
  */
 
 #ifdef STM32_MEDIUM_DENSITY
@@ -64,32 +80,18 @@
 #endif
 #endif
 
-/**
- * \def NR_GPIO_PORTS
- * Number of GPIO ports
- */
-
-/* SRAM_SIZE intentionally not part of Doxygen interface */
-
-/**
- * \def DELAY_US_MULT
- * Multiplier to convert microseconds into loop iterations in delay_us().
+/*
+ * MCU-specific configuration.
  *
- * @see delay_us()
+ * If you add something here, make sure to include documentation for
+ * it in the __DOXYGEN_PREDEFINED_HACK section, below.
  */
 
-/* MCU-specific configuration */
 #if defined(MCU_STM32F103RB)
     /* e.g., LeafLabs Maple */
 
-    /* Number of GPIO ports (GPIOA, GPIOB, etc.) */
     #define NR_GPIO_PORTS              4
-
-    /* SRAM size, in bytes */
     #define SRAM_SIZE             0x5000
-
-    /* Multiplier to convert microseconds into loop iterations in
-     * delay_us() (See delay.h) */
     #define DELAY_US_MULT             12
 
 #elif defined(MCU_STM32F103ZE)
@@ -124,5 +126,32 @@
 
 #endif
 
-#endif
+/* MCU-specific config documentation.
+ *
+ * Doxygen refuses to trust us when we \def something that it doesn't
+ * notice as a #define.  To work around this, we put
+ * __DOXYGEN_PREDEFINED_HACK into our Doxyfile's PREDEFINED, so that
+ * this section is considered part of the code by doxygen, but not by
+ * an actual compile. */
+
+#ifdef __DOXYGEN_PREDEFINED_HACK
+
+    /**
+     * Number of GPIO ports
+     */
+    #define NR_GPIO_PORTS
+
+    /* SRAM_SIZE intentionally not documented as I'm not convinced
+     * it's a good idea [mbolivar]. */
+
+    /**
+     * @brief Multiplier to convert microseconds into loop iterations
+     *        in delay_us().
+     *
+     * @see delay_us()
+     */
+    #define DELAY_US_MULT
+
+#endif  /* __DOXYGEN_PREDEFINED_HACK */
 
+#endif  /* _STM32_H_ */
-- 
cgit v1.2.3