docs: Improve stream documentation

Signed-off-by: Rahix <rahix@rahix.de>

epicardium/epicardium.h

@@ -68,11 +68,18 @@ API(API_LEDS_SET, void epic_leds_set(int led, uint8_t r, uint8_t g, uint8_t b));
 
 /**
  * Read sensor data into a buffer.  ``epic_stream_read()`` will read as many
- * sensor data packets as possible into ``buf`` and return as soon as possible.
- * It will poke the sensor driver once to check whether new data can be fetched.
- * If there is no new sensor data, ``epic_stream_read()`` will return ``0`` and
- * not touch ``buf``.  Otherwise it will return the number of data packets which
- * were read into ``buf``.
+ * sensor samples into the provided buffer as possible and return the number of
+ * samples written.  If no samples are available, ``epic_stream_read()`` will
+ * return ``0`` immediately.
+ *
+ * ``epic_stream_read()`` expects the provided buffer to have a size which is a
+ * multiple of the sample size for the given stream.  For the sample-format and
+ * size, please consult the sensors documentation.
+ *
+ * Before reading the internal sensor sample queue, ``epic_stream_read()`` will
+ * call a sensor specific *poll* function to allow the sensor driver to fetch
+ * new samples from its hardware.  This should, however, never take a long
+ * amount of time.
  *
  * :param int sd: Sensor Descriptor.  You get sensor descriptors as return
  *    values when activating the respective sensors.
@@ -84,8 +91,7 @@ API(API_LEDS_SET, void epic_leds_set(int led, uint8_t r, uint8_t g, uint8_t b));
  *
  *    - ``-ENODEV``: Sensor is not currently available.
  *    - ``-EBADF``: The given sensor descriptor is unknown.
- *    - ``-EINVAL``:  If ``count`` is not a multiple of the sensor data packet
- *      size.
+ *    - ``-EINVAL``:  ``count`` is not a multiple of the sensor's sample size.
  *
  * **Example**:
  *

epicardium/modules/stream.h

@@ -7,8 +7,6 @@
 #include "FreeRTOS.h"
 #include "queue.h"
 
-#define STREAM_QUEUE_WAIT pdMS_TO_TICKS(10)
-
 /**
  * **Stream Descriptors**:
  *
@@ -38,11 +36,14 @@ struct stream_info {
 	/** The size of one data packet (= queue element). */
 	size_t item_size;
 	/**
-	 * An optional function to call before performing the read.
+	 * An optional function to call before performing the read.  Set to
+	 * ``NULL`` if unused.
 	 *
 	 * ``poll_stream()`` is intended for sensors who passively collect data.
 	 * A sensor driver might for example retrieve the latest samples in this
 	 * function instead of actively polling in a task loop.
+	 *
+	 * The function registered here should never block for a longer time.
 	 */
 	int (*poll_stream)();
 };
@@ -50,7 +51,7 @@ struct stream_info {
 /**
  * Register a stream so it can be read from Epicardium API.
  *
- * :param int sd: Stream Descriptor.  Must be from the above enum.
+ * :param int sd: Stream Descriptor.  Must be from the :c:type:`stream_descriptor` enum.
  * :param stream_info stream: Stream info.
  * :returns: ``0`` on success or a negative value on error.  Possible errors:
  *