update documentation for bus_poll

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

3 files changed, 18 insertions, 26 deletions

diff --git a/doc/bus_poll.3 b/doc/bus_poll.3
index 9260f48..b22115c 100644
--- a/doc/bus_poll.3
+++ b/doc/bus_poll.3
@@ -6,21 +6,18 @@ bus_poll_start, bus_poll_stop, bus_poll, bus_poll_timed - Wait a message to be b
 .nf
 #include <bus.h>
 .P
-int bus_poll_start(bus_t *\fIbus\fP, int \fIflags\fP);
+int bus_poll_start(bus_t *\fIbus\fP);
 int bus_poll_stop(const bus_t *\fIbus\fP);
-const char *bus_poll(bus_t *\fIbus\fP);
+const char *bus_poll(bus_t *\fIbus\fP, int \fIflags\fP);
 const char *bus_poll_timed(bus_t *\fIbus\fP, const struct timespec *\fItimeout\fP, clockid_t \fIclockid\fP);
 .fi
 .SH DESCRIPTION
 The
 .BR bus_poll ()
 function waits for a message to broadcasted on the \fIbus\fP, and return
-the message it receives.  The function fails if there is not already a
-message waiting on the bus when the function is called and (\fIflags\fP
-&BUS_NOWAIT) was used the last time
-.BR bus_poll_start ()
-was called.  Received messages shall be copied and parsed, and acted
-upon, in a separate thread, and
+the message it receives.  The function fails if (\fIflags\fP &BUS_NOWAIT)
+and there is not already a message waiting on the bus.  Received messages
+shall be copied and parsed, and acted upon, in a separate thread, and
 .BR bus_poll ()
 or
 .BR bus_poll_stop ()
@@ -44,10 +41,7 @@ it will fail and set \fIerrno\fP to \fBEAGAIN\fP.  The time is specified
 as an absolute time using the parameter \fItimeout\fP.  The behaviour is
 unspecified if \fItimeout\fP is \fINULL\fP. \fItimeout\fP is measured
 with the clock whose ID is specified by the \fIclockid\fP parameter.  This
-clock must be a predicitable clock.  Additionally, the
-.BR bus_poll_start ()
-function must not have been called with (\fIflags\fP &BUS_NOWAIT),
-otherwise the behaviour is undefined.
+clock must be a predicitable clock.
 .SH RETURN VALUES
 Upon successful completion, the functions
 .BR bus_poll_start ()
diff --git a/src/bus.c b/src/bus.c
index 0517f7a..7609de6 100644
--- a/src/bus.c
+++ b/src/bus.c
@@ -978,11 +978,8 @@ done:
  * misbehave, is `bus_poll` is written to expect
  * this function to have been called.
  * 
- * @param   bus    Bus information
- * @param   flags  `BUS_NOWAIT` if the bus should fail and set `errno` to
- *                 `EAGAIN` if there isn't already a message available on
- *                 the bus when `bus_poll` is called
- * @return         0 on success, -1 on error
+ * @param   bus  Bus information
+ * @return       0 on success, -1 on error
  */
 int
 bus_poll_start(bus_t *bus)
@@ -1020,8 +1017,10 @@ bus_poll_stop(const bus_t *bus)
  * started, the caller of this function should then
  * either call `bus_poll` again or `bus_poll_stop`.
  * 
- * @param   bus  Bus information
- * @return       The received message, `NULL` on error
+ * @param   bus    Bus information
+ * @param   flags  `BUS_NOWAIT` if the bus should fail and set `errno` to
+ *                 `EAGAIN` if there 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 9d3b436..36f3a0e 100644
--- a/src/bus.h
+++ b/src/bus.h
@@ -247,11 +247,8 @@ int bus_read_timed(const bus_t *bus, int (*callback)(const char *message, void *
  * misbehave, is `bus_poll` is written to expect
  * this function to have been called.
  * 
- * @param   bus    Bus information
- * @param   flags  `BUS_NOWAIT` if the bus should fail and set `errno` to
- *                 `EAGAIN` if there isn't already a message available on
- *                 the bus when `bus_poll` is called
- * @return         0 on success, -1 on error
+ * @param   bus  Bus information
+ * @return       0 on success, -1 on error
  */
 int bus_poll_start(bus_t *bus);
 
@@ -273,8 +270,10 @@ int bus_poll_stop(const bus_t *bus);
  * started, the caller of this function should then
  * either call `bus_poll` again or `bus_poll_stop`.
  * 
- * @param   bus  Bus information
- * @return       The received message, `NULL` on error
+ * @param   bus    Bus information
+ * @param   flags  `BUS_NOWAIT` if the bus should fail and set `errno` to
+ *                 `EAGAIN` if there 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);