From 86afbc7a0dfcc6e23992ef43f3324388a8087421 Mon Sep 17 00:00:00 2001
From: Adrian Schneider <adrian.schneider@abusix.com>
Date: Sun, 21 Jul 2019 16:27:10 +0200
Subject: [PATCH] chore(light_sensor) add api docs for light sensor

---
 epicardium/epicardium.h | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/epicardium/epicardium.h b/epicardium/epicardium.h
index 392a0e8e..d956c00c 100644
--- a/epicardium/epicardium.h
+++ b/epicardium/epicardium.h
@@ -168,8 +168,41 @@ API(API_INTERRUPT_ENABLE, int epic_interrupt_enable(api_int_id_t int_id));
  */
 API(API_INTERRUPT_DISABLE, int epic_interrupt_disable(api_int_id_t int_id));
 
+/**
+ * Start continuous readout of the light sensor. Will read light level
+ * at preconfigured interval and make it available via `epic_light_sensor_get()`
+ *
+ * :return: `0` if the start was successful or a negative error value
+ *      if an error occured. Possible errors:
+ *
+ *      - ``-EBUSY``: The timer could not be scheduled.
+ *      - ``-EALREADY``: The continuous readout is already running. You can ignore
+ *      this error and safely use `epic_light_sensor_get()` anyways.
+ */
 API(API_LIGHT_SENSOR_RUN, int epic_light_sensor_run());
+
+/**
+ * Get the last light level measured by the continuous readout.
+ *
+ * :param uint16_t* value: where the last light level should be written.
+ * :return: `0` if the readout was successful or a negative error
+ *      value. Possible errors:
+ *
+ *      - ``-ENODATA``: Continuous readout not currently running.
+ */
 API(API_LIGHT_SENSOR_GET, int epic_light_sensor_get(uint16_t* value));
+
+
+/**
+ * Stop continuous readout of the light sensor.
+ *
+ * :return: `0` if the stop was sucessful or a negative error value
+ *      if an error occured. Possible errors:
+ *
+ *      - ``-EBUSY``: The timer stop could not be scheduled.
+ *      - ``-EINVAL``: The continuous readout was not running. The continuous
+ *          readout can be safely restarted.
+ */
 API(API_LIGHT_SENSOR_STOP, int epic_light_sensor_stop());
 
 #endif /* _EPICARDIUM_H */
-- 
GitLab