From f5cd3a4496dd463de472435f707419b5e81d7c51 Mon Sep 17 00:00:00 2001 From: smlng Date: Tue, 6 Jun 2017 13:40:06 +0200 Subject: [PATCH 1/5] doc: reorganize and enhance docu on common I2C periph interface --- drivers/include/periph/i2c.h | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/drivers/include/periph/i2c.h b/drivers/include/periph/i2c.h index fa16653064..61554d5cae 100644 --- a/drivers/include/periph/i2c.h +++ b/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:
* 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 * @author Thomas Eichinger From ab6cb269ed925816fad17255e6665d95490c1cdf Mon Sep 17 00:00:00 2001 From: smlng Date: Tue, 6 Jun 2017 13:41:59 +0200 Subject: [PATCH 2/5] doc: fix UART doxygen docu - move detailed description to be visible on respective module page - see and compare other periph interfaces, i.e., GPIO, PWM ... --- drivers/include/periph/uart.h | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/drivers/include/periph/uart.h b/drivers/include/periph/uart.h index 17f6649295..2a89f0e02f 100644 --- a/drivers/include/periph/uart.h +++ b/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 * From 236c6cb0133f40a6e13141313c91fa56c197ebde Mon Sep 17 00:00:00 2001 From: smlng Date: Tue, 6 Jun 2017 13:45:59 +0200 Subject: [PATCH 3/5] doc: enhance doxygen doc of PM module --- drivers/include/periph/pm.h | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/drivers/include/periph/pm.h b/drivers/include/periph/pm.h index 56432a7760..d4b92afa3c 100644 --- a/drivers/include/periph/pm.h +++ b/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 From 756e3d95fbb525245a5aad3238d3a5fb461960f2 Mon Sep 17 00:00:00 2001 From: smlng Date: Tue, 6 Jun 2017 13:47:25 +0200 Subject: [PATCH 4/5] doc: make detailed description of flashpage interface more visibile --- drivers/include/periph/flashpage.h | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/drivers/include/periph/flashpage.h b/drivers/include/periph/flashpage.h index d5a1e71793..5fce095333 100644 --- a/drivers/include/periph/flashpage.h +++ b/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 */ From 15f8703f015f53efced00549cd27fa0d95cb51d2 Mon Sep 17 00:00:00 2001 From: smlng Date: Tue, 6 Jun 2017 16:07:51 +0200 Subject: [PATCH 5/5] doc: use markdown sections, adapt pwm.h --- drivers/include/periph/pwm.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/drivers/include/periph/pwm.h b/drivers/include/periph/pwm.h index d9ad13ac74..b0540061e5 100644 --- a/drivers/include/periph/pwm.h +++ b/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