Rework comments

Avoid repitions between comments and code. Additionnal usage information
can be added as header comment and additionnal technical information can
be added in the source file

drivers/flash.c

@@ -20,6 +20,11 @@ static volatile struct FLASH* regs = (struct FLASH*)FLASH_BASE_ADDRESS;
 
 //--public functions------------------------------------------------------------
 
+/**
+ * Sets the correct latency to compensate the core's clock speed. Latency must
+ * never be too low or the system will crash due to errors when accessing the
+ * flash, hence the warning in the header
+ */
 void flash_configure(enum FlashPreset preset)
 {
 	//restore default configuration

drivers/rcc.c

@@ -28,6 +28,10 @@ static volatile struct RCC* regs = (struct RCC*)RCC_BASE_ADDRESS;
 
 //--public functions------------------------------------------------------------
 
+/**
+ * Configures the clock sources, PLL, prescalers, etc. All peripherals are
+ * disabled prior to any modifications to avoid unwanted side effects.
+ */
 void rcc_configure(enum RccPreset preset)
 {
 	//disable all peripherals during clock configuration

drivers/rcc.h

@@ -82,51 +82,40 @@ enum RccApb2 {
 //--functions-------------------------------------------------------------------
 
 /**
- * Configures the clocks and buses according to the given preset.
- *
- * @param preset the preset to use for configuration
+ * Configures the clocks and buses according to the given preset. Peripheral
+ * states are kept during the change and additional reconfiguration are
+ * handled automatically for peripherals that rely on a clock timings (timers,
+ * watchdogs, ...)
  */
 void rcc_configure(enum RccPreset preset);
 
 /**
- * Enables peripherals on the APB1 bus according to the given mask.
- *
- * @param mask the mask for the peripherals to enable
+ * Enables peripherals on the APB1 bus
  */
 void rcc_enable_apb1(enum RccApb1 mask);
 
 /**
- * Disables peripherals on the APB1 bus according to the given mask.
- *
- * @param mask the mask for the peripherals to disable
+ * Disables peripherals on the APB1 bus
  */
 void rcc_disable_apb1(enum RccApb1 mask);
 
 /**
- * Resets peripherals on the APB1 bus according to the given mask.
- *
- * @param mask the mask for the peripherals to reset
+ * Resets peripherals on the APB1 bus
  */
 void rcc_reset_apb1(enum RccApb1 mask);
 
 /**
- * Enables peripherals on the APB2 bus according to the given mask.
- *
- * @param mask the mask for the peripherals to enable
+ * Enables peripherals on the APB2 bus
  */
 void rcc_enable_apb2(enum RccApb2 mask);
 
 /**
- * Disables peripherals on the APB2 bus according to the given mask.
- *
- * @param mask the mask for the peripherals to disable
+ * Disables peripherals on the APB2 bus
  */
 void rcc_disable_apb2(enum RccApb2 mask);
 
 /**
- * Resets peripherals on the APB2 bus according to the given mask.
- *
- * @param mask the mask for the peripherals to reset
+ * Resets peripherals on the APB2 bus
  */
 void rcc_reset_apb2(enum RccApb2 mask);