From f0b0db8f06929b1e207674b504d12483e83493d1 Mon Sep 17 00:00:00 2001 From: Hauke Petersen Date: Thu, 19 Nov 2015 17:13:33 +0100 Subject: [PATCH] drivers: various doxygen fixes - fixed group naming scheme to 'drivers_xx' - introduced a group for actuators (analog to the sensors) - added missing doxygen to ltc4150 driver --- drivers/doc.txt | 9 ++++ drivers/include/adc_legacy.h | 14 ++++--- drivers/include/at30tse75x.h | 4 +- drivers/include/dht.h | 2 +- drivers/include/diskio.h | 2 +- drivers/include/encx24j600.h | 2 +- drivers/include/flashrom.h | 2 +- drivers/include/gpioint.h | 29 +++++++------ drivers/include/hih6130.h | 2 +- drivers/include/ina220.h | 2 +- drivers/include/isl29020.h | 2 +- drivers/include/isl29125.h | 2 +- drivers/include/l3g4200d.h | 2 +- drivers/include/lis3dh.h | 2 +- drivers/include/lm75a-temp-sensor.h | 2 +- drivers/include/lps331ap.h | 2 +- drivers/include/lsm303dlhc.h | 2 +- drivers/include/ltc4150.h | 64 +++++++++++++++++++++++++++++ drivers/include/ltc4150_arch.h | 49 ++++++++++++++-------- drivers/include/nvram-spi.h | 2 +- drivers/include/nvram.h | 2 +- drivers/include/pcd8544.h | 2 +- drivers/include/rgbled.h | 2 +- drivers/include/servo.h | 2 +- drivers/include/sht11.h | 4 +- drivers/include/tcs37727.h | 3 +- 26 files changed, 154 insertions(+), 58 deletions(-) diff --git a/drivers/doc.txt b/drivers/doc.txt index 983809e884..2962185bbb 100644 --- a/drivers/doc.txt +++ b/drivers/doc.txt @@ -28,3 +28,12 @@ * Most of these drivers will be connected over some bus or serial connection * to the MCU. */ + +/** + * @defgroup drivers_actuators Actuator Device Drivers + * @ingroup drivers + * @brief Drivers for actuating devices + * + * The group of actuators includes all kind of devices that can actively + * interact with the physical world, as e.g. motors, lights, sound devices, etc. + */ diff --git a/drivers/include/adc_legacy.h b/drivers/include/adc_legacy.h index ec7e65e438..45f4a02390 100644 --- a/drivers/include/adc_legacy.h +++ b/drivers/include/adc_legacy.h @@ -10,17 +10,19 @@ * @defgroup drivers_adc ADC * @ingroup drivers * @brief Generic interface for ADC drivers + * * @deprecated This interface is obsolete. Use the @ref drivers_periph_adc * interface in @ref drivers_periph instead. + * @{ + * + * @file + * @brief Legacy ADC driver interface * * @author Oliver Hahm - * - * @{ - * @file */ -#ifndef ADC_H -#define ADC_H +#ifndef ADC_LEGACY_H +#define ADC_LEGACY_H #include @@ -46,5 +48,5 @@ uint16_t adc_read(uint8_t channel); } #endif +#endif /* ADC_LEGACY_H */ /** @} */ -#endif /* ADC_H */ diff --git a/drivers/include/at30tse75x.h b/drivers/include/at30tse75x.h index 1c35d8ff53..adccd607a3 100644 --- a/drivers/include/at30tse75x.h +++ b/drivers/include/at30tse75x.h @@ -7,8 +7,8 @@ */ /** - * @defgroup at30tse75x AT30TSE75x temperature sensor with EEPROM - * @ingroup drivers + * @defgroup drivers_at30tse75x AT30TSE75x temperature sensor with EEPROM + * @ingroup drivers_sensors * * The connection between the MCU and the AT30TSE75x is based on the * I2C-interface. There are 3 versions of this IC, with either 2/4/8 Kb of diff --git a/drivers/include/dht.h b/drivers/include/dht.h index 38382ffe9e..375fb95ed5 100644 --- a/drivers/include/dht.h +++ b/drivers/include/dht.h @@ -7,7 +7,7 @@ */ /** - * @defgroup driver_dht DHT Family of Humidity and Temperature Sensors + * @defgroup drivers_dht DHT Family of Humidity and Temperature Sensors * @ingroup drivers_sensors * @brief Device driver for the DHT Family of humidity * and temperature sensors diff --git a/drivers/include/diskio.h b/drivers/include/diskio.h index 02f859756c..7c321ff70e 100644 --- a/drivers/include/diskio.h +++ b/drivers/include/diskio.h @@ -7,7 +7,7 @@ */ /** - * @defgroup diskio Disk IO Driver + * @defgroup drivers_diskio Disk IO Driver * @ingroup drivers * @brief Low level disk interface * diff --git a/drivers/include/encx24j600.h b/drivers/include/encx24j600.h index 971113bad8..d8317c8443 100644 --- a/drivers/include/encx24j600.h +++ b/drivers/include/encx24j600.h @@ -7,7 +7,7 @@ */ /** - * @defgroup driver_encx24j600 ENCX24J600 + * @defgroup drivers_encx24j600 ENCX24J600 * @ingroup drivers_netdev * @brief Driver for the ENCX24J600 Ethernet Adapter * @{ diff --git a/drivers/include/flashrom.h b/drivers/include/flashrom.h index 343f48e19f..d6ccafb862 100644 --- a/drivers/include/flashrom.h +++ b/drivers/include/flashrom.h @@ -7,7 +7,7 @@ */ /** - * @defgroup flashrom Flash memory driver + * @defgroup drivers_flashrom Flash memory driver * @ingroup drivers * @brief Generic flash memory driver * @{ diff --git a/drivers/include/gpioint.h b/drivers/include/gpioint.h index dda336c028..6070ee6bbf 100644 --- a/drivers/include/gpioint.h +++ b/drivers/include/gpioint.h @@ -6,9 +6,6 @@ * directory for more details. */ -#ifndef GPIOINT_H_ -#define GPIOINT_H_ - /** * @defgroup drivers_gpioint GPIO IRQ Multiplexer * @ingroup drivers @@ -24,6 +21,9 @@ * @author Michael Baar */ +#ifndef GPIOINT_H_ +#define GPIOINT_H_ + #include #include @@ -32,19 +32,21 @@ extern "C" { #endif /* - * gpioint_flags: - * Note: - We rely on the exact values for the edges. - * - These flags are extended in hal/drivers/device-gpio.h + * @brief GPIO IRQ multiplexer flags + * + * @note We rely on the exact values for the edges. + * @note These flags are extended in hal/drivers/device-gpio.h + * + * @{ */ -#define GPIOINT_DISABLE 0x00 -#define GPIOINT_RISING_EDGE 0x01 ///< interrupt is generated on rising edge -#define GPIOINT_FALLING_EDGE 0x02 ///< interrupt is generated on falling edge -#define GPIOINT_DEBOUNCE 0x04 ///< debounce this interrupt +#define GPIOINT_DISABLE 0x00 /**< disable interrupt */ +#define GPIOINT_RISING_EDGE 0x01 /**< interrupt is generated on rising edge */ +#define GPIOINT_FALLING_EDGE 0x02 /**< interrupt is generated on falling edge */ +#define GPIOINT_DEBOUNCE 0x04 /**< debounce this interrupt */ +/** @} */ /** * @brief GPIO IRQ callback function type - * @param[in] data User defined callback data passed through gpioint_set - * @param[in] edge A combination of GPIOINT_RISING_EDGE and GPIOINT_FALLING_EDGE */ typedef void(*fp_irqcb)(void); @@ -62,6 +64,9 @@ typedef void(*fp_irqcb)(void); */ bool gpioint_set(int port, uint32_t bitmask, int flags, fp_irqcb callback); +/** + * @brief Initialize the multiplexer + */ void gpioint_init(void); #ifdef __cplusplus diff --git a/drivers/include/hih6130.h b/drivers/include/hih6130.h index 25ba8e5ef1..3d3712e802 100644 --- a/drivers/include/hih6130.h +++ b/drivers/include/hih6130.h @@ -7,7 +7,7 @@ */ /** - * @defgroup driver_hih6130 HIH6130 humidity and temperature sensor + * @defgroup drivers_hih6130 HIH6130 humidity and temperature sensor * @ingroup drivers_sensors * @brief Device driver for Honeywell HumidIcon Digital * Humidity/Temperature Sensors: HIH-6130/6131 Series diff --git a/drivers/include/ina220.h b/drivers/include/ina220.h index 27577b61b6..9906b99a1d 100644 --- a/drivers/include/ina220.h +++ b/drivers/include/ina220.h @@ -7,7 +7,7 @@ */ /** - * @defgroup driver_ina220 INA220 current/power monitor + * @defgroup drivers_ina220 INA220 current/power monitor * @ingroup drivers_sensors * @brief Device driver for Texas Instruments INA220 High or Low Side, * Bi-Directional CURRENT/POWER MONITOR with Two-Wire Interface diff --git a/drivers/include/isl29020.h b/drivers/include/isl29020.h index 1dbee4f84b..37d702df32 100644 --- a/drivers/include/isl29020.h +++ b/drivers/include/isl29020.h @@ -7,7 +7,7 @@ */ /** - * @defgroup driver_isl29020 ISL29020 light sensor + * @defgroup drivers_isl29020 ISL29020 light sensor * @ingroup drivers_sensors * @brief Device driver for the ISL29020 light sensor * @{ diff --git a/drivers/include/isl29125.h b/drivers/include/isl29125.h index b9b9e5ac6f..9221828100 100644 --- a/drivers/include/isl29125.h +++ b/drivers/include/isl29125.h @@ -7,7 +7,7 @@ */ /** - * @defgroup driver_isl29125 ISL29125 RGB light sensor + * @defgroup drivers_isl29125 ISL29125 RGB light sensor * @ingroup drivers_sensors * @brief Device driver for the ISL29125 RGB light sensor * diff --git a/drivers/include/l3g4200d.h b/drivers/include/l3g4200d.h index b1be174596..b73b3a734b 100644 --- a/drivers/include/l3g4200d.h +++ b/drivers/include/l3g4200d.h @@ -7,7 +7,7 @@ */ /** - * @defgroup driver_l3g4200d L3G4200D gyroscope + * @defgroup drivers_l3g4200d L3G4200D gyroscope * @ingroup drivers_sensors * @brief Device driver for the L3G4200D gyroscope * @{ diff --git a/drivers/include/lis3dh.h b/drivers/include/lis3dh.h index 38515cad7d..3fcccbe1fa 100644 --- a/drivers/include/lis3dh.h +++ b/drivers/include/lis3dh.h @@ -7,7 +7,7 @@ */ /** - * @defgroup driver_lis3dh LIS3DH accelerometer + * @defgroup drivers_lis3dh LIS3DH accelerometer * @ingroup drivers_sensors * @brief Device driver for the LIS3DH accelerometer * @{ diff --git a/drivers/include/lm75a-temp-sensor.h b/drivers/include/lm75a-temp-sensor.h index 37696ab29c..560edca24b 100644 --- a/drivers/include/lm75a-temp-sensor.h +++ b/drivers/include/lm75a-temp-sensor.h @@ -7,7 +7,7 @@ */ /** - * @defgroup lm75a LM75A + * @defgroup drivers_lm75a LM75A * @ingroup drivers_sensors * @brief Driver for the LM75A digital temperature sensor and thermal watchdog * diff --git a/drivers/include/lps331ap.h b/drivers/include/lps331ap.h index dd4f49c971..513b471faf 100644 --- a/drivers/include/lps331ap.h +++ b/drivers/include/lps331ap.h @@ -7,7 +7,7 @@ */ /** - * @defgroup driver_lps331ap LPS331AP Pressure Sensor Driver + * @defgroup drivers_lps331ap LPS331AP Pressure Sensor Driver * @ingroup drivers_sensors * @brief Device driver for the LPS331AP pressure sensor * @{ diff --git a/drivers/include/lsm303dlhc.h b/drivers/include/lsm303dlhc.h index 5b2a1cc649..b060a478c5 100644 --- a/drivers/include/lsm303dlhc.h +++ b/drivers/include/lsm303dlhc.h @@ -7,7 +7,7 @@ */ /** - * @defgroup driver_lsm303dlhc LSM303DLHC 3D accelerometer/magnetometer + * @defgroup drivers_lsm303dlhc LSM303DLHC 3D accelerometer/magnetometer * @ingroup drivers_sensors * @brief Device driver for the LSM303DLHC 3D accelerometer/magnetometer * @{ diff --git a/drivers/include/ltc4150.h b/drivers/include/ltc4150.h index 757f8e8244..85b1ad7096 100644 --- a/drivers/include/ltc4150.h +++ b/drivers/include/ltc4150.h @@ -6,6 +6,23 @@ * directory for more details. */ +/** + * @defgroup drivers_ltc4150 LTC4150 Coulomb Counter + * @ingroup drivers_sensors + * @brief Device driver for LTC4150 coulomb counters + * + * @deprecated This driver should be ported to the peripheral driver interface + * (@ref drivers_periph) + * + * @{ + * + * @file + * @brief Driver interface for the LTC4150 driver + * + * @author Heiko Will + */ + + #ifndef LTC4150_H #define LTC4150_H @@ -15,15 +32,61 @@ extern "C" { #endif +/** + * @brief Initialize the counter + */ void ltc4150_init(void); + +/** + * @brief Start a measurement + */ void ltc4150_start(void); + +/** + * @brief End the ongoing measurement + */ void ltc4150_stop(void); +/** + * @brief Get the current electrical current + * + * @return electrical current in mA + */ double ltc4150_get_current_mA(void); + +/** + * @brief Get the total power used since @p ltc4150_start was called + * + * @return power used in mAh + */ double ltc4150_get_total_mAh(void); + +/** + * @brief Get the total energy used since @p ltc4150_start was called + * + * @return energy used in Joule + */ double ltc4150_get_total_Joule(void); + +/** + * @brief Get the average electrical current sine @p ltc4150_start was called + * + * @return average current in mA + */ double ltc4150_get_avg_mA(void); + +/** + * @brief Get the time the current measurement is going on + * + * @return time + */ int ltc4150_get_interval(void); + +/** + * @brief Get the number of samples taken + * + * @return number of samples in the current interval + */ long ltc4150_get_intcount(void); #ifdef __cplusplus @@ -31,3 +94,4 @@ long ltc4150_get_intcount(void); #endif #endif /* LTC4150_H */ +/** @} */ diff --git a/drivers/include/ltc4150_arch.h b/drivers/include/ltc4150_arch.h index 74729d92e7..f3590d8989 100644 --- a/drivers/include/ltc4150_arch.h +++ b/drivers/include/ltc4150_arch.h @@ -6,6 +6,18 @@ * directory for more details. */ +/** + * @defgroup drivers_ltc4150 LTC4150 + * @ingroup drivers_sensors + * @brief Driver for the Linear Technology LTC4150 Coulomb Counter + * @{ + * + * @file + * @brief LTC4150 Coulomb Counter + * + * @author Heiko Will + */ + #ifndef LTC4150_ARCH_H #define LTC4150_ARCH_H @@ -14,34 +26,39 @@ extern "C" { #endif /** - * @defgroup ltc4150 LTC4150 - * @ingroup drivers_sensors - * @brief Driver for the Linear Technology LTC4150 Coulomb Counter + * @brief Constants used by the driver * @{ - * - * @file - * @brief LTC4150 Coulomb Counter - * - * @author Heiko Will */ - #define _GFH (double)32.631375 #define _R_SENSE (double)0.330 #define SUPPLY_VOLTAGE (5) +/** @} */ -/** board specific ltc4150 interrupt disable */ +/** + * @brief Board specific ltc4150 interrupt disable + **/ void ltc4150_disable_int(void); -/** board specific ltc4150 interrupt enable */ + +/** + * @brief Board specific ltc4150 interrupt enable + **/ void ltc4150_enable_int(void); -/** board specific synchronization of ltc4150 */ + +/** + * @brief Board specific synchronization of ltc4150 + **/ void ltc4150_sync_blocking(void); -/** board specific ltc4150 initialization */ + +/** + * @brief Board specific ltc4150 initialization + **/ void ltc4150_arch_init(void); /** - * ltc4150 interrupt handler, - * shall be called on ltc4150 interrupt, - * implemented in driver + * @brief Ltc4150 interrupt handler + * + * This handler shall be called on ltc4150 interrupt, it is implemented in the + * driver. */ void ltc4150_interrupt(void); diff --git a/drivers/include/nvram-spi.h b/drivers/include/nvram-spi.h index e8699f314a..45a8e77c35 100644 --- a/drivers/include/nvram-spi.h +++ b/drivers/include/nvram-spi.h @@ -7,7 +7,7 @@ */ /** - * @ingroup nvram + * @ingroup drivers_nvram * @{ * * @file diff --git a/drivers/include/nvram.h b/drivers/include/nvram.h index d738464620..6467c993c1 100644 --- a/drivers/include/nvram.h +++ b/drivers/include/nvram.h @@ -7,7 +7,7 @@ */ /** - * @defgroup nvram Non-volatile RAM + * @defgroup drivers_nvram Non-volatile RAM * @ingroup drivers * @brief Non-volatile RAM interface * diff --git a/drivers/include/pcd8544.h b/drivers/include/pcd8544.h index bda2cbc621..79304616be 100644 --- a/drivers/include/pcd8544.h +++ b/drivers/include/pcd8544.h @@ -8,7 +8,7 @@ /** * @defgroup driver_pcd8544 PCD8544 LCD driver - * @ingroup drivers + * @ingroup drivers_actuators * @brief Driver for PCD8544 LCD displays * * @{ diff --git a/drivers/include/rgbled.h b/drivers/include/rgbled.h index c53cd63bb0..b952043177 100644 --- a/drivers/include/rgbled.h +++ b/drivers/include/rgbled.h @@ -8,7 +8,7 @@ /** * @defgroup driver_rgbled RGB-LED driver - * @ingroup drivers + * @ingroup drivers_actuators * @brief High-level driver for RGB-LEDs * @{ * diff --git a/drivers/include/servo.h b/drivers/include/servo.h index c264f4ff74..082361e9d9 100644 --- a/drivers/include/servo.h +++ b/drivers/include/servo.h @@ -9,7 +9,7 @@ /** * @defgroup driver_servo Servo Motor Driver - * @ingroup drivers + * @ingroup drivers_actuators * @brief High-level driver for servo motors * @{ * diff --git a/drivers/include/sht11.h b/drivers/include/sht11.h index a01564ec2c..82df5e8ea3 100644 --- a/drivers/include/sht11.h +++ b/drivers/include/sht11.h @@ -10,9 +10,9 @@ #define SHT11_H_ /** - * @defgroup sht11 SHT11 - * @brief Driver for Sensirion SHT11 Humidity and Temperature Sensor + * @defgroup drivers_sht11 SHT11 * @ingroup drivers_sensors + * @brief Driver for Sensirion SHT11 Humidity and Temperature Sensor * @{ * * @file diff --git a/drivers/include/tcs37727.h b/drivers/include/tcs37727.h index ff9bd67497..4eee7045be 100644 --- a/drivers/include/tcs37727.h +++ b/drivers/include/tcs37727.h @@ -8,8 +8,7 @@ /** * @defgroup drivers_tcs37727 TCS37727 Light-To-Digital Converter - * - * @ingroup drivers + * @ingroup drivers_sensors * @brief Driver for the AMS TCS37727 Color Light-To-Digital Converter * *