[PATCH 5/6] utils: Ensure wl_list's doxygen formats properly

[Aaron Faanes]

This changes the "struct foo" mentions to use <tt>, which appears as
monospaced font. This also wraps code examples with \code tags to
ensure they're detected as code.

The code example uses C++ style // comments. I would have preferred to
use /* */ comments for consistency, but this is not possible since we're
already in this type of block comment. Doxygen picks it up fine,
however.

This commit doesn't contain any changes in terms of wording. Most of the
diff noise is due to the whitespace changes. git diff -w should help
point out the real changes.
---
 src/wayland-util.h | 44 +++++++++++++++++++++++++-------------------
 1 file changed, 25 insertions(+), 19 deletions(-)

diff --git a/src/wayland-util.h b/src/wayland-util.h
index 31a1ac2..51de3f6 100644
--- a/src/wayland-util.h
+++ b/src/wayland-util.h
@@ -70,39 +70,45 @@ struct wl_interface {
  *
  * \brief doubly-linked list
  *
- * The list head is of "struct wl_list" type, and must be initialized
- * using wl_list_init().  All entries in the list must be of the same
- * type.  The item type must have a "struct wl_list" member. This
- * member will be initialized by wl_list_insert(). There is no need to
- * call wl_list_init() on the individual item. To query if the list is
- * empty in O(1), use wl_list_empty().
+ * The list head is of <tt>struct wl_list</tt> type, and must be initialized
+ * using #wl_list_init.  All entries in the list must be of the same
+ * type.  The item type must have a <tt>struct wl_list</tt> member. This
+ * member will be initialized by #wl_list_insert. There is no need to
+ * call #wl_list_init  on the individual item. To query if the list is
+ * empty in O(1), use #wl_list_empty.
  *
- * Let's call the list reference "struct wl_list foo_list", the item type as
- * "item_t", and the item member as "struct wl_list link".
+ * Let's call the list reference <tt>struct wl_list foo_list</tt>, the item type as
+ * <tt>item_t</tt>, and the item member as <tt>struct wl_list link</tt>.
  *
  * The following code will initialize a list:
  *
- * 	struct wl_list foo_list;
+ * \code
+ * struct wl_list foo_list;
  *
- * 	struct item_t {
- * 		int foo;
- * 		struct wl_list link;
- * 	};
- * 	struct item_t item1, item2, item3;
+ * struct item_t {
+ * 	int foo;
+ * 	struct wl_list link;
+ * };
+ * struct item_t item1, item2, item3;
  *
- *	wl_list_init(&foo_list);
- *	wl_list_insert(&foo_list, &item1.link);	Pushes item1 at the head
- *	wl_list_insert(&foo_list, &item2.link);	Pushes item2 at the head
- *	wl_list_insert(&item2.link, &item3.link); Pushes item3 after item2
+ * wl_list_init(&foo_list);
+ * wl_list_insert(&foo_list, &item1.link);   // Pushes item1 at the head
+ * wl_list_insert(&foo_list, &item2.link);   // Pushes item2 at the head
+ * wl_list_insert(&item2.link, &item3.link); // Pushes item3 after item2
+ * \endcode
  *
- * The list now looks like [item2, item3, item1]
+ * The list now looks like <tt>[item2, item3, item1]</tt>
  *
  * Will iterate the list in ascending order:
  *
+ * \code
  *	item_t *item;
  *	wl_list_for_each(item, foo_list, link) {
  *		Do_something_with_item(item);
  *	}
+ * \endcode
+ *
+ * \sa wl_container_of
  */
 struct wl_list {
 	struct wl_list *prev;
-- 
1.8.3.1