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

[Kristian Høgsberg]

On Sun, Sep 15, 2013 at 01:37:10PM -0500, Aaron Faanes wrote:
> 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.

Is there a doxygen markup we can use instead of <tt>?  Most of the
<tt> uses are for types that doxygen should have a tag for, I
believe.  And if we have to use html, maybe <code> is better?

> 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.

Perhaps we could use / instead of a literal / ?

> 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
> 
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel