Merge pull request #4319 from haukepetersen/doc_drivers_fixgroups

drivers: various doxygen fixes

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.
+ */

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 <oliver.hahm@inria.fr>
- *
- * @{
- * @file
  */
 
-#ifndef ADC_H
+#ifndef ADC_LEGACY_H
-#define ADC_H
+#define ADC_LEGACY_H
 
 #include <stdint.h>
 
@@ -46,5 +48,5 @@ uint16_t adc_read(uint8_t channel);
 }
 #endif
 
+#endif /* ADC_LEGACY_H */
 /** @} */
-#endif /* ADC_H */

drivers/include/at30tse75x.h

@@ -7,8 +7,8 @@
  */
 
 /**
- * @defgroup    at30tse75x AT30TSE75x temperature sensor with EEPROM
+ * @defgroup    drivers_at30tse75x AT30TSE75x temperature sensor with EEPROM
- * @ingroup     drivers
+ * @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

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

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
  *

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
  * @{

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
  * @{

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 <michael.baar@fu-berlin.de>
  */
 
+#ifndef GPIOINT_H_
+#define GPIOINT_H_
+
 #include <stdint.h>
 #include <stdbool.h>
 
@@ -32,19 +32,21 @@ extern "C" {
 #endif
 
 /*
- * gpioint_flags:
+ * @brief   GPIO IRQ multiplexer flags
- * Note: - We rely on the exact values for the edges.
+ *
- *       - These flags are extended in hal/drivers/device-gpio.h
+ * @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_DISABLE         0x00    /**< disable interrupt */
-#define GPIOINT_RISING_EDGE     0x01            ///< interrupt is generated on rising edge
+#define GPIOINT_RISING_EDGE     0x01    /**< interrupt is generated on rising edge */
-#define GPIOINT_FALLING_EDGE    0x02            ///< interrupt is generated on falling edge
+#define GPIOINT_FALLING_EDGE    0x02    /**< interrupt is generated on falling edge */
-#define GPIOINT_DEBOUNCE        0x04            ///< debounce this interrupt
+#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

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

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

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
  * @{

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
  *

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
  * @{

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
  * @{

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
  *

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
  * @{

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
  * @{

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 <heiko.will@fu-berlin.de>
+ */
+
+
 #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 */
+/** @} */

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 <heiko.will@fu-berlin.de>
+ */
+
 #ifndef LTC4150_ARCH_H
 #define LTC4150_ARCH_H
 
@@ -14,34 +26,39 @@ extern "C" {
 #endif
 
 /**
- * @defgroup    ltc4150 LTC4150
+ * @brief   Constants used by the driver
- * @ingroup     drivers_sensors
- * @brief       Driver for the Linear Technology LTC4150 Coulomb Counter
  * @{
- *
- * @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,
+ * @brief   Ltc4150 interrupt handler
- * shall be called on ltc4150 interrupt,
+ *
- * implemented in driver
+ * This handler shall be called on ltc4150 interrupt, it is implemented in the
+ * driver.
  */
 void ltc4150_interrupt(void);
 

drivers/include/nvram-spi.h

@@ -7,7 +7,7 @@
  */
 
 /**
- * @ingroup     nvram
+ * @ingroup     drivers_nvram
  * @{
  *
  * @file

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
  *

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
  *
  * @{

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
  * @{
  *

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
  * @{
  *

drivers/include/sht11.h

@@ -10,9 +10,9 @@
 #define SHT11_H_
 
 /**
- * @defgroup    sht11   SHT11
+ * @defgroup    drivers_sht11   SHT11
- * @brief       Driver for Sensirion SHT11 Humidity and Temperature Sensor
  * @ingroup     drivers_sensors
+ * @brief       Driver for Sensirion SHT11 Humidity and Temperature Sensor
  * @{
  *
  * @file

drivers/include/tcs37727.h

@@ -8,8 +8,7 @@
 
 /**
  * @defgroup    drivers_tcs37727 TCS37727 Light-To-Digital Converter
- *
+ * @ingroup     drivers_sensors
- * @ingroup     drivers
  * @brief       Driver for the AMS TCS37727 Color Light-To-Digital Converter
  *
  *