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