buffer_list: add functions documentation

bufferlist_* functions have no documentation whatsoever and the name is
not always enough to fully understand what the function is doing.
For this reason and for the sake of having better documented code, add
function doc in buffer.h.

Signed-off-by: Antonio Quartulli <a@unstable.cc>
Acked-by: Steffan Karger <steffan@karger.me>
Message-Id: <20181010083731.31132-1-a@unstable.cc>
URL: https://www.mail-archive.com/openvpn-devel@lists.sourceforge.net/msg17701.html
Signed-off-by: David Sommerseth <davids@openvpn.net>
(cherry picked from commit e72b2f2ce062c76c6ab658b7ae961f8b81cba307)

diff --git a/src/openvpn/buffer.h b/src/openvpn/buffer.h
index e37254c94aa81b2e93dd033017048056ef8a4786..c510c005deb65d2dc2c4225f1963e26cd11d0a91 100644 (file)
--- a/src/openvpn/buffer.h
+++ b/src/openvpn/buffer.h
@@ -1082,26 +1082,93 @@ struct buffer_list
     int max_size;            /* maximum size list should grow to */
 };
 
+/**
+ * Allocate an empty buffer list of capacity \c max_size.
+ *
+ * @param max_size  the capacity of the list to allocate
+ *
+ * @return the new list
+ */
 struct buffer_list *buffer_list_new(const int max_size);
 
+/**
+ * Frees a buffer list and all the buffers in it.
+ *
+ * @param ol    the list to free
+ */
 void buffer_list_free(struct buffer_list *ol);
 
+/**
+ * Checks if the list is valid and non-empty
+ *
+ * @param ol    the list to check
+ *
+ * @return true iff \c ol is not NULL and contains at least one buffer
+ */
 bool buffer_list_defined(const struct buffer_list *ol);
 
+/**
+ * Empty the list \c ol and frees all the contained buffers
+ *
+ * @param ol    the list to reset
+ */
 void buffer_list_reset(struct buffer_list *ol);
 
+/**
+ * Allocates and appends a new buffer containing \c str as data to \c ol
+ *
+ * @param ol    the list to append the new buffer to
+ * @param str   the string to copy into the new buffer
+ */
 void buffer_list_push(struct buffer_list *ol, const char *str);
 
+/**
+ * Allocates and appends a new buffer containing \c data of length \c size.
+ *
+ * @param ol    the list to append the new buffer to
+ * @param data  the data to copy into the new buffer
+ * @param size  the length of \c data to copy into the buffer
+ *
+ * @return the new buffer
+ */
 struct buffer_entry *buffer_list_push_data(struct buffer_list *ol, const void *data, size_t size);
 
+/**
+ * Retrieve the head buffer
+ *
+ * @param ol    the list to retrieve the buffer from
+ *
+ * @return a pointer to the head buffer or NULL if the list is empty
+ */
 struct buffer *buffer_list_peek(struct buffer_list *ol);
 
 void buffer_list_advance(struct buffer_list *ol, int n);
 
 void buffer_list_pop(struct buffer_list *ol);
 
+/**
+ * Aggregates as many buffers as possible from \c bl in a new buffer of maximum
+ * length \c max_len .
+ * All the aggregated buffers are removed from the list and replaced by the new
+ * one, followed by any additional (non-aggregated) data.
+ *
+ * @param bl    the list of buffer to aggregate
+ * @param max   the maximum length of the aggregated buffer
+ */
 void buffer_list_aggregate(struct buffer_list *bl, const size_t max);
 
+/**
+ * Aggregates as many buffers as possible from \c bl in a new buffer
+ * of maximum length \c max_len . \c sep is written after
+ * each copied buffer (also after the last one). All the aggregated buffers are
+ * removed from the list and replaced by the new one, followed by any additional
+ * (non-aggregated) data.
+ * Nothing happens if \c max_len is not enough to aggregate at least 2 buffers.
+ *
+ * @param bl        the list of buffer to aggregate
+ * @param max_len   the maximum length of the aggregated buffer
+ * @param sep       the separator to put between buffers during aggregation
+ */
 void buffer_list_aggregate_separator(struct buffer_list *bl,
                                      const size_t max_len, const char *sep);