buffer_list: add functions documentation

index cb9e9dff..dbc5bfc3 100644
@@ -1091,26 +1091,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);
 
+/**
+ * Allocatea 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);