4 files changed, 22 insertions, 8 deletions
diff --git a/libmaple/include/libmaple/rcc.h b/libmaple/include/libmaple/rcc.h
index 9042391..4693606 100644
--- a/libmaple/include/libmaple/rcc.h
+++ b/libmaple/include/libmaple/rcc.h
@@ -42,7 +42,7 @@ extern "C"{
  * might need them. */
 /**
  * @brief SYSCLK sources
- * @see rcc_clk_init()
+ * @see rcc_switch_sysclk()
  */
 typedef enum rcc_sysclk_src {
     RCC_CLKSRC_HSI = 0x0,
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
diff --git a/libmaple/stm32f2/include/series/rcc.h b/libmaple/stm32f2/include/series/rcc.h
index 019bb3e..79bdf73 100644
--- a/libmaple/stm32f2/include/series/rcc.h
+++ b/libmaple/stm32f2/include/series/rcc.h
@@ -833,7 +833,7 @@ typedef enum rcc_clk_id {
 
 /**
  * @brief PLL entry clock source
- * @see rcc_clk_init()
+ * @see rcc_configure_pll()
  */
 typedef enum rcc_pllsrc {
     RCC_PLLSRC_HSI = 0,