Add concise explanations

- explain functions in list.h
- let lxc_list_len() return size_t instead of int

Signed-off-by: Christian Brauner <christian.brauner@mailbox.org>
Acked-by: Stéphane Graber <stgraber@ubuntu.com>

diff --git a/src/lxc/list.h b/src/lxc/list.h
index 2d8a2a84da51bac3bce23061473334ef227fb310..91ea3a4954fbade13a60b569be8258cab3a9f9f9 100644 (file)
--- a/src/lxc/list.h
+++ b/src/lxc/list.h
@@ -32,42 +32,71 @@ struct lxc_list {
 
 #define lxc_init_list(l) { .next = l, .prev = l }
 
+/*
+ * Iterate through an lxc list. An example for an idiom would be:
+ *
+ * struct lxc_list *iterator;
+ * type *tmp; // where "type" can be an int, char * etc.
+ * lxc_list_for_each(iterator, list) {
+ *       tmp = iterator->elem;
+ *        // Do stuff with tmp.
+ * }
+ * free(iterator);
+ */
 #define lxc_list_for_each(__iterator, __list)                          \
        for (__iterator = (__list)->next;                               \
             __iterator != __list;                                      \
             __iterator = __iterator->next)
 
+/*
+ * Iterate safely through an lxc list. An example for an appropriate use case
+ * would be:
+ *
+ * struct lxc_list *iterator;
+ * lxc_list_for_each_safe(iterator, list, list->next) {
+ *       tmp = iterator->elem;
+ *        // Do stuff with tmp.
+ * }
+ * free(iterator);
+ */
 #define lxc_list_for_each_safe(__iterator, __list, __next)             \
        for (__iterator = (__list)->next, __next = __iterator->next;    \
             __iterator != __list;                                      \
             __iterator = __next, __next = __next->next)
 
+/* Initalize list. */
 static inline void lxc_list_init(struct lxc_list *list)
 {
        list->elem = NULL;
        list->next = list->prev = list;
 }
 
+/* Add an element to a list. See lxc_list_add() and lxc_list_add_tail() for an
+ * idiom. */
 static inline void lxc_list_add_elem(struct lxc_list *list, void *elem)
 {
        list->elem = elem;
 }
 
+/* Retrieve first element of list. */
 static inline void *lxc_list_first_elem(struct lxc_list *list)
 {
        return list->next->elem;
 }
 
+/* Retrieve last element of list. */
 static inline void *lxc_list_last_elem(struct lxc_list *list)
 {
        return list->prev->elem;
 }
 
+/* Determine if list is empty. */
 static inline int lxc_list_empty(struct lxc_list *list)
 {
        return list == list->next;
 }
 
+/* Workhorse to be called from lxc_list_add() and lxc_list_add_tail(). */
 static inline void __lxc_list_add(struct lxc_list *new,
                                  struct lxc_list *prev,
                                  struct lxc_list *next)
@@ -78,17 +107,44 @@ static inline void __lxc_list_add(struct lxc_list *new,
        prev->next = new;
 }
 
+/*
+ * Idiom to add an element to the beginning of an lxc list:
+ *
+ *     struct lxc_list *tmp = malloc(sizeof(*tmp));
+ *     if (tmp == NULL)
+ *             return 1;
+ *     lxc_list_add_elem(tmp, elem);
+ *     lxc_list_add(list, tmp);
+ */
 static inline void lxc_list_add(struct lxc_list *head, struct lxc_list *list)
 {
        __lxc_list_add(list, head, head->next);
 }
 
+/*
+ * Idiom to add an element to the end of an lxc list:
+ *
+ *     struct lxc_list *tmp = malloc(sizeof(*tmp));
+ *     if (tmp == NULL)
+ *             return 1;
+ *     lxc_list_add_elem(tmp, elem);
+ *     lxc_list_add_tail(list, tmp);
+ */
 static inline void lxc_list_add_tail(struct lxc_list *head,
                                     struct lxc_list *list)
 {
        __lxc_list_add(list, head->prev, head);
 }
 
+/*
+ * Idiom to free an lxc list:
+ *
+ * lxc_list_for_each_safe(iterator, list, list->next) {
+ *       lxc_list_del(iterator);
+ *       free(iterator);
+ * }
+ * free(iterator);
+ */
 static inline void lxc_list_del(struct lxc_list *list)
 {
        struct lxc_list *next, *prev;
@@ -99,9 +155,10 @@ static inline void lxc_list_del(struct lxc_list *list)
        prev->next = next;
 }
 
-static inline int lxc_list_len(struct lxc_list *list)
+/* Return length of the list. */
+static inline size_t lxc_list_len(struct lxc_list *list)
 {
-        int i = 0;
+        size_t i = 0;
         struct lxc_list *iter;
         lxc_list_for_each(iter, list) {
                i++;