RCC: Doxygen

Various changes to Doxygen structure, to help leaflabs-docs make sense
of everything.

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

1 files changed, 43 insertions, 45 deletions

diff --git a/libmaple/stm32f1/include/series/rcc.h b/libmaple/stm32f1/include/series/rcc.h
index 3e7f7c6..c20d5d6 100644
--- a/libmaple/stm32f1/include/series/rcc.h
+++ b/libmaple/stm32f1/include/series/rcc.h
@@ -43,7 +43,7 @@ extern "C"{
  * Register map
  */
 
-/** RCC register map type */
+/** STM32F1 RCC register map type */
 typedef struct rcc_reg_map {
     __io uint32 CR;             /**< Clock control register */
     __io uint32 CFGR;           /**< Clock configuration register */
@@ -57,7 +57,6 @@ typedef struct rcc_reg_map {
     __io uint32 CSR;            /**< Control/status register */
 } rcc_reg_map;
 
-/** RCC register map base pointer */
 #define RCC_BASE                        ((struct rcc_reg_map*)0x40021000)
 
 /*
@@ -389,10 +388,7 @@ typedef struct rcc_reg_map {
  */
 
 /**
- * @brief Identifies bus and clock line for a peripheral.
- *
- * Also generally useful as a unique identifier for that peripheral
- * (or its corresponding device struct).
+ * @brief STM32F1 rcc_clk_id.
  */
 typedef enum rcc_clk_id {
     RCC_GPIOA,
@@ -444,28 +440,7 @@ typedef enum rcc_clk_id {
 } rcc_clk_id;
 
 /**
- * @brief Deprecated PLL multipliers, for rcc_clk_init().
- */
-typedef enum rcc_pll_multiplier {
-    RCC_PLLMUL_2 = (0x0 << 18),
-    RCC_PLLMUL_3 = (0x1 << 18),
-    RCC_PLLMUL_4 = (0x2 << 18),
-    RCC_PLLMUL_5 = (0x3 << 18),
-    RCC_PLLMUL_6 = (0x4 << 18),
-    RCC_PLLMUL_7 = (0x5 << 18),
-    RCC_PLLMUL_8 = (0x6 << 18),
-    RCC_PLLMUL_9 = (0x7 << 18),
-    RCC_PLLMUL_10 = (0x8 << 18),
-    RCC_PLLMUL_11 = (0x9 << 18),
-    RCC_PLLMUL_12 = (0xA << 18),
-    RCC_PLLMUL_13 = (0xB << 18),
-    RCC_PLLMUL_14 = (0xC << 18),
-    RCC_PLLMUL_15 = (0xD << 18),
-    RCC_PLLMUL_16 = (0xE << 18),
-} rcc_pll_multiplier;
-
-/**
- * @brief PLL clock sources.
+ * @brief STM32F1 PLL clock sources.
  * @see rcc_configure_pll()
  */
 typedef enum rcc_pllsrc {
@@ -473,6 +448,10 @@ typedef enum rcc_pllsrc {
     RCC_PLLSRC_HSI_DIV_2 = (0x0 << 16)
 } rcc_pllsrc;
 
+/**
+ * @brief STM32F1 clock domains.
+ * @see rcc_dev_clk()
+ */
 typedef enum rcc_clk_domain {
     RCC_APB1,
     RCC_APB2,
@@ -480,7 +459,7 @@ typedef enum rcc_clk_domain {
 } rcc_clk_domain;
 
 /**
- * Prescaler identifiers
+ * @brief STM32F1 Prescaler identifiers
  * @see rcc_set_prescaler()
  */
 typedef enum rcc_prescaler {
@@ -492,7 +471,7 @@ typedef enum rcc_prescaler {
 } rcc_prescaler;
 
 /**
- * ADC prescaler dividers
+ * @brief STM32F1 ADC prescaler dividers
  * @see rcc_set_prescaler()
  */
 typedef enum rcc_adc_divider {
@@ -503,7 +482,7 @@ typedef enum rcc_adc_divider {
 } rcc_adc_divider;
 
 /**
- * APB1 prescaler dividers
+ * @brief STM32F1 APB1 prescaler dividers
  * @see rcc_set_prescaler()
  */
 typedef enum rcc_apb1_divider {
@@ -515,7 +494,7 @@ typedef enum rcc_apb1_divider {
 } rcc_apb1_divider;
 
 /**
- * APB2 prescaler dividers
+ * @brief STM32F1 APB2 prescaler dividers
  * @see rcc_set_prescaler()
  */
 typedef enum rcc_apb2_divider {
@@ -527,7 +506,7 @@ typedef enum rcc_apb2_divider {
 } rcc_apb2_divider;
 
 /**
- * AHB prescaler dividers
+ * @brief STM32F1 AHB prescaler dividers
  * @see rcc_set_prescaler()
  */
 typedef enum rcc_ahb_divider {
@@ -544,7 +523,7 @@ typedef enum rcc_ahb_divider {
 } rcc_ahb_divider;
 
 /**
- * @brief Available clock sources.
+ * @brief STM32F1 clock sources.
  */
 typedef enum rcc_clk {
     RCC_CLK_PLL    = (uint16)((offsetof(struct rcc_reg_map, CR) << 8) |
@@ -562,26 +541,45 @@ typedef enum rcc_clk {
                                                    * (approximately 32 KHz). */
 } rcc_clk;
 
-/*
- * Series-specific functionality.
+/**
+ * @brief STM32F1 PLL multipliers.
  */
-
-__deprecated
-void rcc_clk_init(rcc_sysclk_src sysclk_src,
-                  rcc_pllsrc pll_src,
-                  rcc_pll_multiplier pll_mul);
+typedef enum rcc_pll_multiplier {
+    RCC_PLLMUL_2 = (0x0 << 18),
+    RCC_PLLMUL_3 = (0x1 << 18),
+    RCC_PLLMUL_4 = (0x2 << 18),
+    RCC_PLLMUL_5 = (0x3 << 18),
+    RCC_PLLMUL_6 = (0x4 << 18),
+    RCC_PLLMUL_7 = (0x5 << 18),
+    RCC_PLLMUL_8 = (0x6 << 18),
+    RCC_PLLMUL_9 = (0x7 << 18),
+    RCC_PLLMUL_10 = (0x8 << 18),
+    RCC_PLLMUL_11 = (0x9 << 18),
+    RCC_PLLMUL_12 = (0xA << 18),
+    RCC_PLLMUL_13 = (0xB << 18),
+    RCC_PLLMUL_14 = (0xC << 18),
+    RCC_PLLMUL_15 = (0xD << 18),
+    RCC_PLLMUL_16 = (0xE << 18),
+} rcc_pll_multiplier;
 
 /**
- * @brief STM32F1-specific PLL configuration values.
- *
- * Use this as the "data" field in a struct rcc_pll_cfg.
- *
+ * @brief STM32F1 PLL configuration values.
+ * Point to one of these with the "data" field in a struct rcc_pll_cfg.
  * @see struct rcc_pll_cfg.
  */
 typedef struct stm32f1_rcc_pll_data {
      rcc_pll_multiplier pll_mul; /**< PLL multiplication factor. */
 } stm32f1_rcc_pll_data;
 
+/*
+ * Deprecated bits.
+ */
+
+__deprecated
+void rcc_clk_init(rcc_sysclk_src sysclk_src,
+                  rcc_pllsrc pll_src,
+                  rcc_pll_multiplier pll_mul);
+
 #ifdef __cplusplus
 }
 #endif