From a2bc258af0ebfc4ea754bbad9e05de3b023b7f12 Mon Sep 17 00:00:00 2001
From: Hauke Petersen <hauke.petersen@fu-berlin.de>
Date: Tue, 27 Jun 2017 11:43:58 +0200
Subject: [PATCH] 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 |  4 ++--
 cpu/stm32_common/periph/dac.c   |  4 ++--
 cpu/stm32f2/periph/dac.c        |  4 ++--
 drivers/include/periph/dac.h    | 22 +++++++++++++++++++---
 4 files changed, 25 insertions(+), 9 deletions(-)

diff --git a/cpu/kinetis_common/periph/dac.c b/cpu/kinetis_common/periph/dac.c
index 8de0f6ca40..d8127e9652 100644
--- a/cpu/kinetis_common/periph/dac.c
+++ b/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)
diff --git a/cpu/stm32_common/periph/dac.c b/cpu/stm32_common/periph/dac.c
index 79797c6c10..a7d3fd846b 100644
--- a/cpu/stm32_common/periph/dac.c
+++ b/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)
diff --git a/cpu/stm32f2/periph/dac.c b/cpu/stm32f2/periph/dac.c
index 397c3a6046..823eca7bb0 100644
--- a/cpu/stm32f2/periph/dac.c
+++ b/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)
diff --git a/drivers/include/periph/dac.h b/drivers/include/periph/dac.h
index f49e32b5fa..c789d19491 100644
--- a/drivers/include/periph/dac.h
+++ b/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