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>

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++;