util: add some documentation for the iobuf helpers

Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>

src/util-io.h

@@ -30,12 +30,20 @@
 #include <string.h>
 #include <unistd.h>
 
+/**
+ * Wrapper around close(). It checks for fd != -1 to satisfy coverity and
+ * friends and always returns -1.
+ */
 static inline int
 xclose(int fd) {
 	if (fd != -1) close(fd);
 	return -1;
 }
 
+/**
+ * Wrapper around read(). Returns the number of bytes read or a negative
+ * errno on failure.
+ */
 static inline int
 xread(int fd, void *buf, size_t count)
 {
@@ -43,6 +51,10 @@ xread(int fd, void *buf, size_t count)
 	return rc == -1 ? -errno : rc;
 }
 
+/**
+ * Wrapper around write(). Returns the number of bytes written or a negative
+ * errno on failure.
+ */
 static inline int
 xwrite(int fd, const void *buf, size_t count)
 {
@@ -50,12 +62,16 @@ xwrite(int fd, const void *buf, size_t count)
 	return rc == -1 ? -errno : rc;
 }
 
+/* consider this struct opaque */
 struct iobuf {
 	size_t sz;
 	size_t len;
 	char *data;
 };
 
+/**
+ * Create a new iobuf structure with the given size.
+ */
 static inline struct iobuf *
 iobuf_new(size_t size)
 {
@@ -74,6 +90,10 @@ iobuf_new(size_t size)
 	return buf;
 }
 
+/**
+ * Resize the buffer. You should never need this one directly, it's a helper
+ * function.
+ */
 static inline void
 iobuf_resize(struct iobuf *buf, size_t to_size)
 {
@@ -84,18 +104,33 @@ iobuf_resize(struct iobuf *buf, size_t to_size)
 	buf->sz = to_size;
 }
 
+/**
+ * The count of data bytes in this buffer.
+ */
 static inline size_t
 iobuf_len(struct iobuf *buf)
 {
 	return buf->len;
 }
 
+/**
+ * Pointer to the data bytes. Note that the buffer is considered binary
+ * data. The caller must ensure that any strings stored in the buffer are
+ * null-terminated.
+ *
+ * The returned pointer only valid in the immediate scope, any iobuf
+ * function may invalidate the pointer.
+ */
 static inline const char *
 iobuf_data(struct iobuf *buf)
 {
 	return buf->data;
 }
 
+/**
+ * Remove the data bytes from the buffer. The caller must free() the data.
+ * The buffer state is the same as iobuf_new() after this call.
+ */
 static inline char *
 iobuf_take_data(struct iobuf *buf)
 {
@@ -108,6 +143,10 @@ iobuf_take_data(struct iobuf *buf)
 	return data;
 }
 
+/**
+ * Append len bytes to the buffer. If the data exceeds the current buffer
+ * size it is resized automatically.
+ */
 static inline void
 iobuf_append(struct iobuf *buf, const char *data, size_t len)
 {
@@ -120,6 +159,14 @@ iobuf_append(struct iobuf *buf, const char *data, size_t len)
 	buf->len += len;
 }
 
+/**
+ * Append all available data from the file descriptor to the pointer. The
+ * file descriptor shold be in O_NONBLOCK or this call will block. If the
+ * data exceeds the current buffer size it is resized automatically.
+ *
+ * @return The number of bytes read or a negative errno on failure. Zero
+ * indicates EOF.
+ */
 static inline int
 iobuf_append_from_fd(struct iobuf *buf, int fd)
 {
@@ -141,7 +188,10 @@ iobuf_append_from_fd(struct iobuf *buf, int fd)
 	return nread == 0 ? rc : (int)nread;
 }
 
-
+/**
+ * Release the memory associated with this iobuf. Use iobuf_take_data()
+ * prevent the data from being free()d.
+ */
 static inline struct iobuf *
 iobuf_free(struct iobuf *buf)
 {
@@ -156,4 +206,9 @@ iobuf_free(struct iobuf *buf)
 }
 
 static inline void _iobuf_cleanup(struct iobuf **buf) { iobuf_free(*buf); }
+/**
+ * Helper macro to auto-free a iobuf struct when the variable goes out of
+ * scope. Use like this:
+ *    _cleanup_iobuf_ struct iobuf *foo = iobuf_new(64);
+ */
 #define _cleanup_iobuf_ __attribute__((cleanup(_iobuf_cleanup)))