doc: periph: various fixes and cleanup

- unify file/module @brief
- distinct @file section more visibly in source
- provide missing @brief's
- move module details/notes from file to module sections
- provide missing macro definition for building

doc/doxygen/riot.doxyfile

@@ -1980,6 +1980,7 @@ INCLUDE_FILE_PATTERNS  =
 PREDEFINED             = __attribute__(x)= \
                          ADC_NUMOF \
                          CPUID_ID_LEN \
+                         DAC_NUMOF \
                          GPIO_NUMOF \
                          I2C_NUMOF \
                          PWM_NUMOF \

drivers/include/periph/cpuid.h

@@ -9,10 +9,13 @@
 /**
  * @defgroup    driver_periph_cpuid CPUID
  * @ingroup     driver_periph
- * @{
+ * @brief       Low-level CPU ID peripheral driver
  *
+ * Provides access the CPU's serial number
+ *
+ * @{
  * @file
- * @brief       Provides access the CPU's serial number
+ * @brief       Low-level CPUID peripheral driver interface definitions
  *
  * @author      Martine Lenders <mlenders@inf.fu-berlin.de>
  */

drivers/include/periph/dac.h

@@ -10,8 +10,8 @@
  * @defgroup    driver_periph_dac DAC
  * @ingroup     driver_periph
  * @brief       Low-level DAC peripheral driver
- * @{
  *
+ * @{
  * @file
  * @brief       Low-level DAC peripheral driver interface definitions
  *
@@ -28,15 +28,15 @@
 extern "C" {
 #endif
 
-/* guard file in case no ADC device is defined */
+/* guard file in case no DAC device is defined */
 #if DAC_NUMOF
 
 /**
-  * @brief Definition avialable DAC devices
+ * @brief Definition avialable DAC devices
-  *
+ *
-  * Each DAC device is based on a hardware DAC which can have one or more
+ * Each DAC device is based on a hardware DAC which can have one or more
-  * independet channels.
+ * independet channels.
-  */
+ */
 typedef enum {
 #if DAC_0_EN
     DAC_0 = 0,             /**< DAC device 0 */

drivers/include/periph/gpio.h

@@ -10,8 +10,8 @@
  * @defgroup    driver_periph_gpio GPIO
  * @ingroup     driver_periph
  * @brief       Low-level GPIO peripheral driver
- * @{
  *
+ * @{
  * @file
  * @brief       Low-level GPIO peripheral driver interface definitions
  *

drivers/include/periph/i2c.h

@@ -10,8 +10,8 @@
  * @defgroup    driver_periph_i2c I2C
  * @ingroup     driver_periph
  * @brief       Low-level I2C peripheral driver
- * @{
  *
+ * @{
  * @file
  * @brief       Low-level I2C peripheral driver interface definition
  *

drivers/include/periph/pwm.h

@@ -10,8 +10,8 @@
  * @defgroup    driver_periph_pwm PWM
  * @ingroup     driver_periph
  * @brief       Low-level PWM peripheral driver
- * @{
  *
+ * @{
  * @file
  * @brief       Low-level PWM peripheral driver interface definitions
  *

drivers/include/periph/random.h

@@ -9,12 +9,9 @@
 /**
  * @defgroup    driver_periph_random Random
  * @ingroup     driver_periph
- * @{
+ * @brief       Low-level (pseudo) random number generator driver
  *
- * @file
+ * The quality of the random data read from this interface is highly
- * @brief       (Pseudo) random number generator low-level driver interface
- *
- * NOTE: The quality of the random data read from this interface is highly
  * dependent on hardware dependent implementation. Most platforms utilize a
  * hardware (Pseudo) Random Number Generator. The quality of the generated
  * random data can be however very different.
@@ -22,6 +19,10 @@
  * @note REFER TO YOUR PLATFORMS IMPLEMENTATION ABOUT INFORMATION ABOUT THE
  *       QUALITY OF RANDOMNES!
  *
+ * @{
+ * @file
+ * @brief       Low-level random peripheral driver interface definitions
+ *
  * @author      Christian Mehlis <mehlis@inf.fu-berlin.de>
  */
 

drivers/include/periph/rtc.h

@@ -10,8 +10,8 @@
  * @defgroup    driver_periph_rtc RTC
  * @ingroup     driver_periph
  * @brief       Low-level RTC (Real Time Clock) peripheral driver
- * @{
  *
+ * @{
  * @file
  * @brief       Low-level RTC peripheral driver interface definitions
  *

drivers/include/periph/rtt.h

@@ -9,8 +9,9 @@
 /**
  * @defgroup    driver_periph_rtt RTT
  * @ingroup     driver_periph
- * @{
+ * @brief       Low-level RTT (Real Time Timer) peripheral driver
  *
+ * @{
  * @file
  * @brief       Low-level RTT (Real Time Timer) peripheral driver interface
  *              definitions

drivers/include/periph/spi.h

@@ -10,15 +10,15 @@
  * @defgroup    driver_periph_spi SPI
  * @ingroup     driver_periph
  * @brief       Low-level SPI peripheral driver
- * @{
- *
- * @file
- * @brief       Low-level SPI peripheral driver interface definitions
  *
  * The current design of this interface targets implementations that use the SPI in blocking mode.
  *
  * TODO: add means for asynchronous SPI usage
  *
+ * @{
+ * @file
+ * @brief       Low-level SPI peripheral driver interface definitions
+ *
  * @author      Hauke Petersen <hauke.petersen@fu-berlin.de>
  */