[PATCH 6/6] utils: Document wl_list methods
---
As I understand it, a wl_list can be either content-bearing node or a list head.
I believe this is correct, but if it isn't (in other words, there is no
distinction
between list heads and content-bearing elements), then this documentation is
going
to be tragically incorrect.
src/wayland-util.h | 64 ++
1 file changed, 64 insertions(+)
diff --git a/src/wayland-util.h b/src/wayland-util.h
index 51de3f6..86d03f2 100644
--- a/src/wayland-util.h
+++ b/src/wayland-util.h
@@ -115,11 +115,75 @@ struct wl_list {
struct wl_list *next;
};
+/** Initializes a new wl_list for use as a list.
+ *
+ * There is no need to call this method for wl_list nodes that will only be
used as
+ * elements within other lists, though there is no harm in doing so.
+ *
+ * \param list The list that will be initialized.
+ *
+ * \memberof wl_list
+ */
void wl_list_init(struct wl_list *list);
+
+/** Inserts the specified element directly after the specified list node.
+ *
+ * \param list the list that will be directly previous to \c elm
+ * \param elm The element that will be added after \c list
+ *
+ * \memberof wl_list
+ */
void wl_list_insert(struct wl_list *list, struct wl_list *elm);
+
+/** Removes the specified wl_list node from the list that contains it.
+ *
+ * \param elm the list to remove
+ *
+ * \memberof wl_list
+ */
void wl_list_remove(struct wl_list *elm);
+
+/** Returns the number of elements in the specified list.
+ *
+ * Prefer #wl_list_empty if you're just interested if the list is empty.
+ *
+ * \param list The list that will be queried.
+ * \return The number of elements in the specified list.
+ *
+ * \sa wl_list_empty
+ * \memberof wl_list
+ */
int wl_list_length(const struct wl_list *list);
+
+/** Queries whether the specified list is empty.
+ *
+ * This method runs in O(1).
+ *
+ * \param list The list that will be queried.
+ * \return \c true if the list is empty, \c false otherwise
+ *
+ * \sa wl_list_length
+ * \memberof wl_list
+ */
int wl_list_empty(const struct wl_list *list);
+
+/** Inserts all elements in the specified other list into \c list.
+ *
+ * All elements in \other will be added in order directly before \c list.
+ *
+ * \code
+ * wl_list foo; // [1, 2, 3]
+ * wl_list bar; // [4, 5, 6]
+ *
+ * wl_list_insert_list(&foo, &other);
+ * // foo now contains [4, 5, 6, 1, 2, 3]
+ * \endcode
+ *
+ * \param list The list that will be added to
+ * \param other The list that contains the elements to add.
+ *
+ * \memberof wl_list
+ */
void wl_list_insert_list(struct wl_list *list, struct wl_list *other);
/**
--
1.8.3.1
___
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/wayland-devel
Re: [PATCH 6/6] utils: Document wl_list methods
On Sun, Sep 15, 2013 at 01:37:11PM -0500, Aaron Faanes wrote:
> ---
>
> As I understand it, a wl_list can be either content-bearing node or a list
> head.
> I believe this is correct, but if it isn't (in other words, there is no
> distinction
> between list heads and content-bearing elements), then this documentation is
> going
> to be tragically incorrect.
No, you're right. A list has a dummy struct wl_list as the head
element (typically embedded in the struct that owns the list) and the
rest of the elements carray actual data (embedded in the structs that
are the elements of the list).
> src/wayland-util.h | 64
> ++
> 1 file changed, 64 insertions(+)
>
> diff --git a/src/wayland-util.h b/src/wayland-util.h
> index 51de3f6..86d03f2 100644
> --- a/src/wayland-util.h
> +++ b/src/wayland-util.h
> @@ -115,11 +115,75 @@ struct wl_list {
> struct wl_list *next;
> };
>
> +/** Initializes a new wl_list for use as a list.
Let's be more precise and say "as a list head" here.
> + *
> + * There is no need to call this method for wl_list nodes that will only be
> used as
> + * elements within other lists, though there is no harm in doing so.
> + *
> + * \param list The list that will be initialized.
> + *
> + * \memberof wl_list
> + */
> void wl_list_init(struct wl_list *list);
> +
> +/** Inserts the specified element directly after the specified list node.
Maybe we can add something like: The list node can be either the list
head, in which case the element is prepended to the list, or the last
list node, in which case the element will be appended to the list.
> + *
> + * \param list the list that will be directly previous to \c elm
> + * \param elm The element that will be added after \c list
> + *
> + * \memberof wl_list
> + */
> void wl_list_insert(struct wl_list *list, struct wl_list *elm);
> +
> +/** Removes the specified wl_list node from the list that contains it.
> + *
> + * \param elm the list to remove
> + *
> + * \memberof wl_list
> + */
> void wl_list_remove(struct wl_list *elm);
> +
> +/** Returns the number of elements in the specified list.
> + *
> + * Prefer #wl_list_empty if you're just interested if the list is empty.
> + *
> + * \param list The list that will be queried.
> + * \return The number of elements in the specified list.
> + *
> + * \sa wl_list_empty
> + * \memberof wl_list
> + */
> int wl_list_length(const struct wl_list *list);
> +
> +/** Queries whether the specified list is empty.
> + *
> + * This method runs in O(1).
> + *
> + * \param list The list that will be queried.
> + * \return \c true if the list is empty, \c false otherwise
> + *
> + * \sa wl_list_length
> + * \memberof wl_list
> + */
> int wl_list_empty(const struct wl_list *list);
> +
> +/** Inserts all elements in the specified other list into \c list.
> + *
> + * All elements in \other will be added in order directly before \c list.
> + *
> + * \code
> + * wl_list foo; // [1, 2, 3]
> + * wl_list bar; // [4, 5, 6]
> + *
> + * wl_list_insert_list(&foo, &other);
> + * // foo now contains [4, 5, 6, 1, 2, 3]
> + * \endcode
I'd spell out that bar is now undefined and needs to be re-initialized
with wl_list_init() if we're going to add elements to it again.
Kristian
> + * \param list The list that will be added to
> + * \param other The list that contains the elements to add.
> + *
> + * \memberof wl_list
> + */
> void wl_list_insert_list(struct wl_list *list, struct wl_list *other);
>
> /**
> --
> 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
Re: [PATCH 6/6] utils: Document wl_list methods
On Tue, Sep 17, 2013 at 12:15 AM, Kristian Høgsberg wrote:
> On Sun, Sep 15, 2013 at 01:37:11PM -0500, Aaron Faanes wrote:
> > +/** Inserts the specified element directly after the specified list
> node.
> > + *
> > + * \param list the list that will be directly previous to \c elm
> > + * \param elm The element that will be added after \c list
> > + *
> > + * \memberof wl_list
> > + */
> > void wl_list_insert(struct wl_list *list, struct wl_list *elm);
>
Maybe we can add something like: The list node can be either the list
> head, in which case the element is prepended to the list, or the last
> list node, in which case the element will be appended to the list.
>
/** Inserts the specified element into the specified list.
*
* If \c list is a list head, then \c elm will be prepended to that list.
* Otherwise, if \c list is another node, then \c elm will be inserted
directly
* after it (or appended if \c list is the last list node).
*
* \param list Either a list node or a list head
* \param elm The element that will be added after \c list
*
* \memberof wl_list
*/
void wl_list_insert(struct wl_list *list, struct wl_list *elm);
I tried to be more specific in how list heads vs. list nodes are handled. I
may have misunderstood you here, so lemme know if you wanted to specify
that only prepending and appending are supported, as I'm assuming that
insertion at any node is allowed (at least ones that are in lists).
> +/** Inserts all elements in the specified other list into \c list.
> > + *
> > + * All elements in \other will be added in order directly before \c
> list.
> > + *
> > + * \code
> > + * wl_list foo; // [1, 2, 3]
> > + * wl_list bar; // [4, 5, 6]
> > + *
> > + * wl_list_insert_list(&foo, &other);
> > + * // foo now contains [4, 5, 6, 1, 2, 3]
> > + * \endcode
>
> I'd spell out that bar is now undefined and needs to be re-initialized
> with wl_list_init() if we're going to add elements to it again.
>
/** Inserts all elements in the specified other list into \c
list.
*
* All elements in \c other will be added in order directly before \c
list.
*
*
~~~
* wl_list list; \comment{[1, 2,
3]}
* wl_list other; \comment{[4, 5,
6]}
*
* wl_list_insert_list(&list,
&other);
* \comment{list now contains [4, 5, 6, 1, 2,
3]}
* \comment{other is now undefined; be sure to call wl_list_init before
reuse}
*
~~~
*
* \param list The list that will be added
to
* \param other The list that contains the elements to add. This list
will
* become undefined after this call; it must be re-initialized
with
* wl_list_init before it can be used
again.
*
* \memberof
wl_list
*/
void wl_list_insert_list(struct wl_list *list, struct wl_list *other);
I updated the comment and the \param to point out the re-iniialization
requirement. I also cleaned up the style a bit (e.g. use \comment instead
of //, don't use foo/bar)
Upon thinking on it, I wonder if it would be more prudent to have
wl_list_insert_list call wl_list_init on the other list instead of leaving
it undefined?
--
Aaron Faanes
___
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/wayland-devel
