2 files changed, 20 insertions, 6 deletions
diff --git a/libmaple/stm32f1/include/series/rcc.h b/libmaple/stm32f1/include/series/rcc.h
index b72c5cf..1eb913a 100644
--- a/libmaple/stm32f1/include/series/rcc.h
+++ b/libmaple/stm32f1/include/series/rcc.h
@@ -448,8 +448,7 @@ typedef enum rcc_clk_id {
 } rcc_clk_id;
 
 /**
- * PLL multipliers
- * @see rcc_clk_init()
+ * @brief Deprecated PLL multipliers, for rcc_clk_init().
  */
 typedef enum rcc_pll_multiplier {
     RCC_PLLMUL_2 = (0x0 << 18),
@@ -470,8 +469,8 @@ typedef enum rcc_pll_multiplier {
 } rcc_pll_multiplier;
 
 /**
- * PLL entry clock source
- * @see rcc_clk_init()
+ * @brief PLL clock sources.
+ * @see rcc_configure_pll()
  */
 typedef enum rcc_pllsrc {
     RCC_PLLSRC_HSE = (0x1 << 16),
diff --git a/libmaple/stm32f1/rcc.c b/libmaple/stm32f1/rcc.c
index 0752b82..aeedf66 100644
--- a/libmaple/stm32f1/rcc.c
+++ b/libmaple/stm32f1/rcc.c
@@ -96,8 +96,23 @@ const struct rcc_dev_info rcc_dev_table[] = {
 };
 
 /**
- * @brief Initialize the clock control system. Initializes the system
- *        clock source to use the PLL driven by an external oscillator
+ * @brief Deprecated.
+ *
+ * Initialize the clock control system. Initializes the system
+ * clock source to use the PLL driven by an external oscillator.
+ *
+ * This function is limited and nonportable. Instead of using it,
+ * follow this (portable) procedure:
+ *
+ * 1. Switch to HSI by calling rcc_switch_sysclk(RCC_CLKSRC_HSI).
+ * 2. Turn off HSE by calling rcc_turn_off_clk(RCC_CLK_HSE).
+ * 3. Turn off the PLL by calling rcc_turn_off_clk(RCC_CLK_HSE).
+ * 4. Reconfigure the PLL using rcc_configure_pll().
+ * 5. Turn on RCC_CLK_HSE using rcc_turn_on_clk() and wait for it to
+ *    become ready by busy-waiting on rcc_is_clk_ready().
+ * 6. Turn on RCC_CLK_PLL using the same methods.
+ * 7. Switch to the PLL with rcc_switch_sysclk(RCC_CLKSRC_PLL).
+ *
  * @param sysclk_src system clock source, must be PLL
  * @param pll_src pll clock source, must be HSE
  * @param pll_mul pll multiplier