doc

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

2 files changed, 113 insertions, 0 deletions

diff --git a/src/bus.c b/src/bus.c
index 6dd6f1a..d97231a 100644
--- a/src/bus.c
+++ b/src/bus.c
@@ -335,6 +335,15 @@ fail:
 
 
 
+/**
+ * Create a new bus
+ * 
+ * @param   file   The pathname of the bus, `NULL` to create a random one
+ * @param   flags  `BUS_EXCL` (if `file` is not `NULL`) to fail if the file
+ *                 already exists, otherwise if the file exists, nothing
+ *                 will happen
+ * @return         The pathname of the bus, `NULL` on error
+ */
 const char *
 bus_create(const char *file, int flags)
 {
@@ -362,6 +371,12 @@ fail:
 }
 
 
+/**
+ * Remove a bus
+ * 
+ * @param   file  The pathname of the bus
+ * @return        0 on success, -1 on error
+ */
 int
 bus_unlink(const char *file)
 {
@@ -388,6 +403,14 @@ fail:
 }
 
 
+/**
+ * Open an existing bus
+ * 
+ * @param   bus    Bus information to fill
+ * @param   file   The filename of the bus
+ * @param   flags  `BUS_RDONLY`, `BUS_WRONLY` or `BUS_RDWR`
+ * @return         0 on success, -1 on error
+ */
 int
 bus_open(bus_t *bus, const char *file, int flags)
 {
@@ -408,17 +431,33 @@ fail:
 }
 
 
+/**
+ * Close a bus
+ * 
+ * @param   bus  Bus information
+ * @return       0 on success, -1 on error
+ */
 int
 bus_close(bus_t *bus)
 {
+	bus->sem_id = -1;
 	if (bus->address)
 		t(close_shared_memory(bus));
+	bus->address = NULL;
 	return 0;
 fail:
 	return -1;
 }
 
 
+/**
+ * Broadcast a message a bus
+ * 
+ * @param   bus      Bus information
+ * @param   message  The message to write, may not be longer than
+ *                   `BUS_MEMORY_SIZE` including the NUL-termination
+ * @return           0 on success, -1 on error
+ */
 int
 bus_write(const bus_t *bus, const char *message)
 {
@@ -434,6 +473,22 @@ fail:
 }
 
 
+/**
+ * Listen (in a loop, forever) for new message on a bus
+ * 
+ * @param   bus       Bus information
+ * @param   callback  Function to call when a message is received, the
+ *                    input parameters will be the read message and
+ *                    `user_data` from `bus_read`'s parameter with the
+ *                    same name. The message must have been parsed or
+ *                    copied when `callback` returns as it may be over
+ *                    overridden after that time. `callback` should
+ *                    return either of the the values:
+ *                      *  0:  stop listening
+ *                      *  1:  continue listening
+ *                      * -1:  an error has occurred
+ * @return            0 on success, -1 on error
+ */
 int
 bus_read(const bus_t *bus, int (*callback)(const char *message, void *user_data), void *user_data)
 {
diff --git a/src/bus.h b/src/bus.h
index faeb2c0..2428574 100644
--- a/src/bus.h
+++ b/src/bus.h
@@ -88,13 +88,71 @@ typedef struct bus
 
 
 
+/**
+ * Create a new bus
+ * 
+ * @param   file   The pathname of the bus, `NULL` to create a random one
+ * @param   flags  `BUS_EXCL` (if `file` is not `NULL`) to fail if the file
+ *                 already exists, otherwise if the file exists, nothing
+ *                 will happen
+ * @return         The pathname of the bus, `NULL` on error
+ */
 const char *bus_create(const char *file, int flags);
+
+/**
+ * Remove a bus
+ * 
+ * @param   file  The pathname of the bus
+ * @return        0 on success, -1 on error
+ */
 int bus_unlink(const char *file);
 
+
+/**
+ * Open an existing bus
+ * 
+ * @param   bus    Bus information to fill
+ * @param   file   The filename of the bus
+ * @param   flags  `BUS_RDONLY`, `BUS_WRONLY` or `BUS_RDWR`
+ * @return         0 on success, -1 on error
+ */
 int bus_open(bus_t *bus, const char *file, int flags);
+
+/**
+ * Close a bus
+ * 
+ * @param   bus  Bus information
+ * @return       0 on success, -1 on error
+ */
 int bus_close(bus_t *bus);
 
+
+/**
+ * Broadcast a message a bus
+ * 
+ * @param   bus      Bus information
+ * @param   message  The message to write, may not be longer than
+ *                   `BUS_MEMORY_SIZE` including the NUL-termination
+ * @return           0 on success, -1 on error
+ */
 int bus_write(const bus_t *bus, const char *message);
+
+/**
+ * Listen (in a loop, forever) for new message on a bus
+ * 
+ * @param   bus       Bus information
+ * @param   callback  Function to call when a message is received, the
+ *                    input parameters will be the read message and
+ *                    `user_data` from `bus_read`'s parameter with the
+ *                    same name. The message must have been parsed or
+ *                    copied when `callback` returns as it may be over
+ *                    overridden after that time. `callback` should
+ *                    return either of the the values:
+ *                      *  0:  stop listening
+ *                      *  1:  continue listening
+ *                      * -1:  an error has occurred
+ * @return            0 on success, -1 on error
+ */
 int bus_read(const bus_t *bus, int (*callback)(const char *message, void *user_data), void *user_data);