doc bus_poll

Signed-off-by: Mattias Andrée <maandree@operamail.com>

2 files changed, 27 insertions, 0 deletions

diff --git a/src/bus.c b/src/bus.c
index 369fa2f..19270fb 100644
--- a/src/bus.c
+++ b/src/bus.c
@@ -766,6 +766,19 @@ bus_poll_stop(const bus_t *bus)
 }
 
 
+/**
+ * Wait for a message to be broadcasted on the bus.
+ * The caller should make a copy of the received message,
+ * without freeing the original copy, and parse it in a
+ * separate thread. When the new thread has started be
+ * started, the caller of this function should then
+ * either call `bus_poll` again or `bus_poll_stop`.
+ * 
+ * @param   bus    Bus information
+ * @param   flags  `IPC_NOWAIT` if the bus should fail and set `errno` to
+ *                 `EAGAIN` if this isn't already a message available on the bus
+ * @return         The received message, `NULL` on error
+ */
 const char *
 bus_poll(bus_t *bus, int flags)
 {
diff --git a/src/bus.h b/src/bus.h
index d8112f2..3ab83de 100644
--- a/src/bus.h
+++ b/src/bus.h
@@ -211,6 +211,20 @@ int bus_poll_start(bus_t *bus);
  * @return       0 on success, -1 on error
  */
 int bus_poll_stop(const bus_t *bus);
+
+/**
+ * Wait for a message to be broadcasted on the bus.
+ * The caller should make a copy of the received message,
+ * without freeing the original copy, and parse it in a
+ * separate thread. When the new thread has started be
+ * started, the caller of this function should then
+ * either call `bus_poll` again or `bus_poll_stop`.
+ * 
+ * @param   bus    Bus information
+ * @param   flags  `IPC_NOWAIT` if the bus should fail and set `errno` to
+ *                 `EAGAIN` if this isn't already a message available on the bus
+ * @return         The received message, `NULL` on error
+ */
 const char *bus_poll(bus_t *bus, int flags);