Merge pull request #7142 from smlng/enh/doc/drivers/periph

Doc: several improvements on docu of common periph interfaces

drivers/include/periph/flashpage.h

@@ -11,10 +11,6 @@
  * @ingroup     drivers_periph
  * @brief       Low-level flash page interface
  *
- * @{
- * @file
- * @brief       Low-level flash page peripheral driver interface
- *
  * This interface provides a very simple and straight forward way for writing
  * a MCU's internal flash. This interface is only capable of reading, verifying,
  * and writing complete flash pages, it has no support for partial flash access.
@@ -27,6 +23,10 @@
  *              around 10K times), so using this interface in some kind of loops
  *              can damage you MCU!
  *
+ * @{
+ * @file
+ * @brief       Low-level flash page peripheral driver interface
+ *
  * @author      Hauke Petersen <hauke.petersen@fu-berlin.de>
  */
 

drivers/include/periph/i2c.h

@@ -11,12 +11,20 @@
  * @ingroup     drivers_periph
  * @brief       Low-level I2C peripheral driver
  *
- * @{
- * @file
- * @brief       Low-level I2C peripheral driver interface definition
+ * This is a simple I2C interface to allow platform independent access to a
+ * MCU's I2C bus and peripherals. This interface is intentionally designed as
+ * simple as possible, to allow for easy implementation and maximal portability.
+ *
+ * @note        The current version of this interface only supports the
+ *              7-bit addressing mode.
+ *
+ * @note        This interface is due for remodeling, hence API changes are to
+ *              be expected for upcoming releases.
+ *
+ * ## A note on pull-up resistors for SDA/SCL
  *
  * The I2C signal lines SDA/SCL need external pull-up resistors which connect
- * the lines to the positive voltage supply Vcc. The I2C driver implementation
+ * the lines to the positive voltage supply VCC. The I2C driver implementation
  * should enable the pin's internal pull-up resistors. There are however some
  * use cases for which the internal pull resistors are not strong enough and the
  * I2C bus will show faulty behavior. This can for example happen when
@@ -44,8 +52,9 @@
  * For more details refer to section 7.1 in:<br>
  * http://www.nxp.com/documents/user_manual/UM10204.pdf
  *
- * @note        The current version of this interface only supports the
-                7-bit addressing mode.
+ * @{
+ * @file
+ * @brief       Low-level I2C peripheral driver interface definition
  *
  * @author      Hauke Petersen <hauke.petersen@fu-berlin.de>
  * @author      Thomas Eichinger <thomas.eichinger@fu-berlin.de>

drivers/include/periph/pm.h

@@ -10,9 +10,10 @@
  * @defgroup    drivers_periph_pm Power Management
  * @ingroup     drivers_periph
  * @brief       The kernels power management interface
- * @{
  *
- * This interface *must* be implemented for every platform in RIOT.
+ * @attention This interface *must* be implemented for every platform in RIOT.
+ *
+ * @{
  *
  * @file
  * @brief       Power management interface

drivers/include/periph/pwm.h

@@ -38,7 +38,7 @@
  * pwm_set() function to change the duty cycle for a given channel. If you
  * want to disable the PWM generation again, simply call pwm_poweroff().
  *
- * @section     sec_pm (Low-) power implications
+ * ## (Low-)Power implications
  *
  * After initialization, the a PWM peripheral **should** be powered on and
  * active. When manually stopped using the pwm_poweroff() function, the PWM

drivers/include/periph/uart.h

@@ -10,7 +10,6 @@
  * @defgroup    drivers_periph_uart UART
  * @ingroup     drivers_periph
  * @brief       Low-level UART peripheral driver
- * @{
  *
  * This is a basic UART (Universal Asynchronous Receiver Transmitter) interface
  * to allow platform independent access to the MCU's serial communication abilities.
@@ -35,6 +34,8 @@
  * in RIOT which is used for standard input/output functions like `printf()` or
  * `puts()`.
  *
+ * @{
+ *
  * @file
  * @brief       Low-level UART peripheral driver interface definition
  *