From 77b790375f4e6899a6a30b62b8be6b66564d41ae Mon Sep 17 00:00:00 2001 From: Hauke Petersen Date: Thu, 19 Nov 2015 15:54:52 +0100 Subject: [PATCH 1/3] drivers/periph: some doxygen fixes - added todos to periph module description - repaired group names (e.g. s/driver_xx/drivers_xx/) --- drivers/include/periph/adc.h | 4 ++-- drivers/include/periph/cpuid.h | 4 ++-- drivers/include/periph/dac.h | 4 ++-- drivers/include/periph/dev_enums.h | 6 +++--- drivers/include/periph/doc.txt | 18 ++++++++++++------ drivers/include/periph/gpio.h | 4 ++-- drivers/include/periph/i2c.h | 4 ++-- drivers/include/periph/pwm.h | 4 ++-- drivers/include/periph/random.h | 4 ++-- drivers/include/periph/rtc.h | 4 ++-- drivers/include/periph/rtt.h | 4 ++-- drivers/include/periph/spi.h | 4 ++-- drivers/include/periph/timer.h | 4 ++-- drivers/include/periph/uart.h | 4 ++-- 14 files changed, 39 insertions(+), 33 deletions(-) diff --git a/drivers/include/periph/adc.h b/drivers/include/periph/adc.h index d6c841087..b009dc812 100644 --- a/drivers/include/periph/adc.h +++ b/drivers/include/periph/adc.h @@ -7,8 +7,8 @@ */ /** - * @defgroup driver_periph_adc ADC - * @ingroup driver_periph + * @defgroup drivers_periph_adc ADC + * @ingroup drivers_periph * @brief Low-level ADC peripheral driver * @{ * diff --git a/drivers/include/periph/cpuid.h b/drivers/include/periph/cpuid.h index 792965901..fabcd011c 100644 --- a/drivers/include/periph/cpuid.h +++ b/drivers/include/periph/cpuid.h @@ -7,8 +7,8 @@ */ /** - * @defgroup driver_periph_cpuid CPUID - * @ingroup driver_periph + * @defgroup drivers_periph_cpuid CPUID + * @ingroup drivers_periph * @brief Low-level CPU ID peripheral driver * * Provides access the CPU's serial number diff --git a/drivers/include/periph/dac.h b/drivers/include/periph/dac.h index b827ece48..bf30e546a 100644 --- a/drivers/include/periph/dac.h +++ b/drivers/include/periph/dac.h @@ -7,8 +7,8 @@ */ /** - * @defgroup driver_periph_dac DAC - * @ingroup driver_periph + * @defgroup drivers_periph_dac DAC + * @ingroup drivers_periph * @brief Low-level DAC peripheral driver * * @{ diff --git a/drivers/include/periph/dev_enums.h b/drivers/include/periph/dev_enums.h index 95e026ad8..f8238913e 100644 --- a/drivers/include/periph/dev_enums.h +++ b/drivers/include/periph/dev_enums.h @@ -7,15 +7,15 @@ */ /** - * @ingroup driver_periph + * @ingroup drivers_periph * * @{ * @file * @brief Device enumerations for backward compatibility with existing * peripheral driver implementations * - * TODO: Remove this file once all peripheral drivers are ported to the more - * efficient implementations style + * @todo Remove this file once all peripheral drivers are ported to the + * more efficient implementations style * * @author Hauke Petersen */ diff --git a/drivers/include/periph/doc.txt b/drivers/include/periph/doc.txt index fa91a5cc2..3dc1a4953 100644 --- a/drivers/include/periph/doc.txt +++ b/drivers/include/periph/doc.txt @@ -1,5 +1,5 @@ /* - * Copyright (C) 2013 Freie Universität Berlin + * Copyright (C) 2013-2015 Freie Universität Berlin * * This file is subject to the terms and conditions of the GNU Lesser * General Public License v2.1. See the file LICENSE in the top level @@ -7,11 +7,17 @@ */ /** - * @defgroup driver_periph Peripheral drivers + * @defgroup drivers_periph Peripheral Driver Interface * @ingroup drivers - * @brief Low-level peripheral drivers + * @brief Low-level peripheral driver interface for vendor and platform + * independent access to MCU peripherals as UART, SPI, etc * - * The module contains the low-level peripheral driver layer. It consists of a set - * of platform independent interface definitions and cpu specific implementations - * for every targeted platform. + * The module contains the low-level peripheral driver interface. This interface + * defines a standardized interface to access MCU peripherals that is not tied + * to any specific vendor, platform or architecture. + * + * @todo describe concept in detail + * @todo link to driver model + * @todo describe/link implementation guide + * @todo list best practices */ diff --git a/drivers/include/periph/gpio.h b/drivers/include/periph/gpio.h index c8c6cae87..cef16f302 100644 --- a/drivers/include/periph/gpio.h +++ b/drivers/include/periph/gpio.h @@ -7,8 +7,8 @@ */ /** - * @defgroup driver_periph_gpio GPIO - * @ingroup driver_periph + * @defgroup drivers_periph_gpio GPIO + * @ingroup drivers_periph * @brief Low-level GPIO peripheral driver * * @{ diff --git a/drivers/include/periph/i2c.h b/drivers/include/periph/i2c.h index 052e3272f..81ffebc4d 100644 --- a/drivers/include/periph/i2c.h +++ b/drivers/include/periph/i2c.h @@ -7,8 +7,8 @@ */ /** - * @defgroup driver_periph_i2c I2C - * @ingroup driver_periph + * @defgroup drivers_periph_i2c I2C + * @ingroup drivers_periph * @brief Low-level I2C peripheral driver * * @{ diff --git a/drivers/include/periph/pwm.h b/drivers/include/periph/pwm.h index a64eebcfa..875131060 100644 --- a/drivers/include/periph/pwm.h +++ b/drivers/include/periph/pwm.h @@ -7,8 +7,8 @@ */ /** - * @defgroup driver_periph_pwm PWM - * @ingroup driver_periph + * @defgroup drivers_periph_pwm PWM + * @ingroup drivers_periph * @brief Low-level PWM peripheral driver * * @{ diff --git a/drivers/include/periph/random.h b/drivers/include/periph/random.h index 7eb587d96..4b93adecc 100644 --- a/drivers/include/periph/random.h +++ b/drivers/include/periph/random.h @@ -7,8 +7,8 @@ */ /** - * @defgroup driver_periph_random Random - * @ingroup driver_periph + * @defgroup drivers_periph_random Random + * @ingroup drivers_periph * @brief Low-level (pseudo) random number generator driver * * The quality of the random data read from this interface is highly diff --git a/drivers/include/periph/rtc.h b/drivers/include/periph/rtc.h index 9e336043a..935bb30af 100644 --- a/drivers/include/periph/rtc.h +++ b/drivers/include/periph/rtc.h @@ -7,8 +7,8 @@ */ /** - * @defgroup driver_periph_rtc RTC - * @ingroup driver_periph + * @defgroup drivers_periph_rtc RTC + * @ingroup drivers_periph * @brief Low-level RTC (Real Time Clock) peripheral driver * * @note diff --git a/drivers/include/periph/rtt.h b/drivers/include/periph/rtt.h index 7157e7717..3675c4fa4 100644 --- a/drivers/include/periph/rtt.h +++ b/drivers/include/periph/rtt.h @@ -7,8 +7,8 @@ */ /** - * @defgroup driver_periph_rtt RTT - * @ingroup driver_periph + * @defgroup drivers_periph_rtt RTT + * @ingroup drivers_periph * @brief Low-level RTT (Real Time Timer) peripheral driver * * @{ diff --git a/drivers/include/periph/spi.h b/drivers/include/periph/spi.h index 042408b2d..cd7151e7a 100644 --- a/drivers/include/periph/spi.h +++ b/drivers/include/periph/spi.h @@ -7,8 +7,8 @@ */ /** - * @defgroup driver_periph_spi SPI - * @ingroup driver_periph + * @defgroup drivers_periph_spi SPI + * @ingroup drivers_periph * @brief Low-level SPI peripheral driver * * The current design of this interface targets implementations that use the SPI in blocking mode. diff --git a/drivers/include/periph/timer.h b/drivers/include/periph/timer.h index 623fccc59..7bc6210c0 100644 --- a/drivers/include/periph/timer.h +++ b/drivers/include/periph/timer.h @@ -7,8 +7,8 @@ */ /** - * @defgroup driver_periph_timer Timer - * @ingroup driver_periph + * @defgroup drivers_periph_timer Timer + * @ingroup drivers_periph * @brief Low-level timer peripheral driver * @{ * diff --git a/drivers/include/periph/uart.h b/drivers/include/periph/uart.h index a652b8974..c29f3b4b2 100644 --- a/drivers/include/periph/uart.h +++ b/drivers/include/periph/uart.h @@ -7,8 +7,8 @@ */ /** - * @defgroup driver_periph_uart UART - * @ingroup driver_periph + * @defgroup drivers_periph_uart UART + * @ingroup drivers_periph * @brief Low-level UART peripheral driver * @{ * From 476167a86c3044ed9addefa5dddd44c6c08a3df0 Mon Sep 17 00:00:00 2001 From: Hauke Petersen Date: Thu, 19 Nov 2015 16:08:38 +0100 Subject: [PATCH 2/3] cpu: fixed any doxygen warning realated to 'periph' --- cpu/kinetis_common/include/periph_cpu.h | 5 +++++ cpu/samd21/include/periph_cpu.h | 2 +- 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/cpu/kinetis_common/include/periph_cpu.h b/cpu/kinetis_common/include/periph_cpu.h index b0927710e..0e6029f51 100644 --- a/cpu/kinetis_common/include/periph_cpu.h +++ b/cpu/kinetis_common/include/periph_cpu.h @@ -38,10 +38,15 @@ typedef uint16_t gpio_t; */ #define GPIO_UNDEF (0xffff) +/** + * @brief Definition of pin and port positions in the gpio_t type + * @{ + */ #define GPIO_PORT_SHIFT (8) #define GPIO_PORT_MASK (0xff << (GPIO_PORT_SHIFT)) #define GPIO_PIN_SHIFT (0) #define GPIO_PIN_MASK (0xff << (GPIO_PIN_SHIFT)) +/** @} */ /** * @brief Define a CPU specific GPIO pin generator macro diff --git a/cpu/samd21/include/periph_cpu.h b/cpu/samd21/include/periph_cpu.h index fa65e951d..862871230 100644 --- a/cpu/samd21/include/periph_cpu.h +++ b/cpu/samd21/include/periph_cpu.h @@ -92,7 +92,7 @@ typedef struct { * @brief PWM device configuration data structure */ typedef struct { - Tcc *dev; /*< TCC device to use */ + Tcc *dev; /**< TCC device to use */ pwm_conf_chan_t chan[2]; /**< channel configuration */ } pwm_conf_t; From 95086da431ec1812b9c731f13a30204f7fadee5a Mon Sep 17 00:00:00 2001 From: Hauke Petersen Date: Thu, 19 Nov 2015 16:09:25 +0100 Subject: [PATCH 3/3] doc/drivers/sys: fixed all refs to drivers_periph_xx --- doc/doxygen/src/mainpage.md | 2 +- drivers/include/adc_legacy.h | 4 ++-- sys/include/net/gnrc/slip.h | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/doxygen/src/mainpage.md b/doc/doxygen/src/mainpage.md index 531fe12f7..0a09b3bda 100644 --- a/doc/doxygen/src/mainpage.md +++ b/doc/doxygen/src/mainpage.md @@ -138,7 +138,7 @@ switching) code. For most CPUs you will also find the linker scripts in the `ldscripts` sub-directory. In the `periph` sub-directory of each CPU you can find the implementations of -the CPU's peripheral drivers like SPI, UART, GPIO, etc. See @ref driver_periph +the CPU's peripheral drivers like SPI, UART, GPIO, etc. See @ref drivers_periph for their API documentation. Many CPUs share a certain amount of their code (e.g. all ARM Cortex-M based diff --git a/drivers/include/adc_legacy.h b/drivers/include/adc_legacy.h index c4455cb98..ec7e65e43 100644 --- a/drivers/include/adc_legacy.h +++ b/drivers/include/adc_legacy.h @@ -10,8 +10,8 @@ * @defgroup drivers_adc ADC * @ingroup drivers * @brief Generic interface for ADC drivers - * @deprecated This interface is obsolete. Use the @ref driver_periph_adc - * interface in @ref driver_periph instead. + * @deprecated This interface is obsolete. Use the @ref drivers_periph_adc + * interface in @ref drivers_periph instead. * * @author Oliver Hahm * diff --git a/sys/include/net/gnrc/slip.h b/sys/include/net/gnrc/slip.h index c2743d92b..f21244bef 100644 --- a/sys/include/net/gnrc/slip.h +++ b/sys/include/net/gnrc/slip.h @@ -10,7 +10,7 @@ * @defgroup net_gnrc_slip SLIP * @ingroup net_gnrc * @brief Provides a SLIP interface over UART utilizing - * @ref driver_periph_uart. + * @ref drivers_periph_uart. * @see RFC 1055 * @{ *