drivers/dac: clarified doc and named return values

- added more comprehensive doc to dac_init and dac_set
- named return values for dac_init
- use named return values in existing implementations

cpu/kinetis_common/periph/dac.c

@@ -36,7 +36,7 @@ int8_t dac_init(dac_t line)
 {
     DAC_Type *dac;
     if ((unsigned int)line >= DAC_NUMOF) {
-        return -1;
+        return DAC_NOLINE;
     }
 
     dac = dac_config[line].dev;
@@ -56,7 +56,7 @@ int8_t dac_init(dac_t line)
 
     /* Set output value to zero */
     dac_set(line, 0);
-    return 0;
+    return DAC_OK;
 }
 
 void dac_set(dac_t line, uint16_t value)

cpu/stm32_common/periph/dac.c

@@ -42,7 +42,7 @@ static const dac_conf_t dac_config[] = DAC_CONFIG;
 int8_t dac_init(dac_t line)
 {
     if (line >= DAC_NUMOF) {
-        return -1;
+        return DAC_NOLINE;
     }
 
     /* configure pin */
@@ -59,7 +59,7 @@ int8_t dac_init(dac_t line)
     /* reset output and enable the line's channel */
     dac_set(line, 0);
     dac_poweron(line);
-    return 0;
+    return DAC_OK;
 }
 
 void dac_set(dac_t line, uint16_t value)

cpu/stm32f2/periph/dac.c

@@ -40,7 +40,7 @@ static const dac_conf_t dac_config[] = {};
 int8_t dac_init(dac_t line)
 {
     if (line >= DAC_NUMOF) {
-        return -1;
+        return DAC_NOLINE;
     }
 
     /* configure pin */
@@ -50,7 +50,7 @@ int8_t dac_init(dac_t line)
     /* reset output and enable the line's channel */
     dac_set(line, 0);
     dac_poweron(line);
-    return 0;
+    return DAC_OK;
 }
 
 void dac_set(dac_t line, uint16_t value)

drivers/include/periph/dac.h

@@ -57,6 +57,14 @@ typedef unsigned int dac_t;
 #endif
 /** @} */
 
+/**
+ * @brief   Return codes used by the DAC driver interface
+ */
+enum {
+    DAC_OK     = 0,
+    DAC_NOLINE = -1
+};
+
 /**
  * @brief   Default DAC undefined value
  * @{
@@ -78,15 +86,23 @@ typedef unsigned int dac_t;
 /**
  * @brief   Initialize the given DAC line
  *
+ * After initialization, the corresponding DAC line is active and its output is
+ * set to 0.
+ *
  * @param[in] line         DAC line to initialize
  *
- * @return                 0 on success
- * @return                 -1 on invalid DAC line
+ * @return  DAC_OK on success
+ * @return  DAC_NOLINE on invalid DAC line
  */
 int8_t dac_init(dac_t line);
 
 /**
- * @brief Write a value onto DAC Device on a given Channel.
+ * @brief   Write a value onto DAC Device on a given Channel
+ *
+ * The value is always given as 16-bit value and is internally scaled to the
+ * actual resolution that the DAC unit provides (e.g. 12-bit). So to get the
+ * maximum output voltage, this function has to be called with @p value set to
+ * 65535 (UINT16_MAX).
  *
  * @param[in] line         DAC line to set
  * @param[in] value        value to set @p line to