From 20cd4936b9d16ee8121d7082d359a76af65081db Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sun, 17 Jul 2011 23:38:58 -0400 Subject: [PATCH] Move GQueue docs inline --- glib/gqueue.c | 25 ++++++++++++++ glib/gqueue.h | 91 ++++++++++++++++++++++++++++++++------------------- 2 files changed, 82 insertions(+), 34 deletions(-) diff --git a/glib/gqueue.c b/glib/gqueue.c index 2f90d6b45..e6bf411b5 100644 --- a/glib/gqueue.c +++ b/glib/gqueue.c @@ -24,6 +24,31 @@ * MT safe */ +/** + * SECTION:queue + * @Title: Double-ended Queues + * @Short_description: double-ended queue data structure + * + * The #GQueue structure and its associated functions provide a standard + * queue data structure. Internally, GQueue uses the same data structure + * as #GList to store elements. + * + * The data contained in each element can be either integer values, by + * using one of the Type + * Conversion Macros, or simply pointers to any type of data. + * + * To create a new GQueue, use g_queue_new(). + * + * To initialize a statically-allocated GQueue, use #G_QUEUE_INIT or + * g_queue_init(). + * + * To add elements, use g_queue_push_head(), g_queue_push_head_link(), + * g_queue_push_tail() and g_queue_push_tail_link(). + * + * To remove elements, use g_queue_pop_head() and g_queue_pop_tail(). + * + * To free the entire queue, use g_queue_free(). + */ #include "config.h" #include "gqueue.h" diff --git a/glib/gqueue.h b/glib/gqueue.h index 345d2c76d..591a09a00 100644 --- a/glib/gqueue.h +++ b/glib/gqueue.h @@ -8,7 +8,7 @@ * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public @@ -35,8 +35,17 @@ G_BEGIN_DECLS -typedef struct _GQueue GQueue; +typedef struct _GQueue GQueue; +/** + * GQueue: + * @head: a pointer to the first element of the queue + * @tail: a pointer to the last element of the queue + * @length: the number of elements in the queue + * + * Contains the public fields of a + * Queue. + */ struct _GQueue { GList *head; @@ -44,6 +53,20 @@ struct _GQueue guint length; }; +/** + * G_QUEUE_INIT: + * + * A statically-allocated #GQueue must be initialized with this + * macro before it can be used. This macro can be used to initialize + * a variable, but it cannot be assigned to a variable. In that case + * you have to use g_queue_init(). + * + * |[ + * GQueue my_queue = G_QUEUE_INIT; + * ]| + * + * Since: 2.14 + */ #define G_QUEUE_INIT { NULL, NULL, 0 } /* Queues @@ -57,70 +80,70 @@ guint g_queue_get_length (GQueue *queue); void g_queue_reverse (GQueue *queue); GQueue * g_queue_copy (GQueue *queue); void g_queue_foreach (GQueue *queue, - GFunc func, - gpointer user_data); + GFunc func, + gpointer user_data); GList * g_queue_find (GQueue *queue, - gconstpointer data); + gconstpointer data); GList * g_queue_find_custom (GQueue *queue, - gconstpointer data, - GCompareFunc func); + gconstpointer data, + GCompareFunc func); void g_queue_sort (GQueue *queue, - GCompareDataFunc compare_func, - gpointer user_data); + GCompareDataFunc compare_func, + gpointer user_data); void g_queue_push_head (GQueue *queue, - gpointer data); + gpointer data); void g_queue_push_tail (GQueue *queue, - gpointer data); + gpointer data); void g_queue_push_nth (GQueue *queue, - gpointer data, - gint n); + gpointer data, + gint n); gpointer g_queue_pop_head (GQueue *queue); gpointer g_queue_pop_tail (GQueue *queue); gpointer g_queue_pop_nth (GQueue *queue, - guint n); + guint n); gpointer g_queue_peek_head (GQueue *queue); gpointer g_queue_peek_tail (GQueue *queue); gpointer g_queue_peek_nth (GQueue *queue, - guint n); + guint n); gint g_queue_index (GQueue *queue, - gconstpointer data); + gconstpointer data); gboolean g_queue_remove (GQueue *queue, - gconstpointer data); + gconstpointer data); guint g_queue_remove_all (GQueue *queue, - gconstpointer data); + gconstpointer data); void g_queue_insert_before (GQueue *queue, - GList *sibling, - gpointer data); + GList *sibling, + gpointer data); void g_queue_insert_after (GQueue *queue, - GList *sibling, - gpointer data); + GList *sibling, + gpointer data); void g_queue_insert_sorted (GQueue *queue, - gpointer data, - GCompareDataFunc func, - gpointer user_data); + gpointer data, + GCompareDataFunc func, + gpointer user_data); void g_queue_push_head_link (GQueue *queue, - GList *link_); + GList *link_); void g_queue_push_tail_link (GQueue *queue, - GList *link_); + GList *link_); void g_queue_push_nth_link (GQueue *queue, - gint n, - GList *link_); + gint n, + GList *link_); GList* g_queue_pop_head_link (GQueue *queue); GList* g_queue_pop_tail_link (GQueue *queue); GList* g_queue_pop_nth_link (GQueue *queue, - guint n); + guint n); GList* g_queue_peek_head_link (GQueue *queue); GList* g_queue_peek_tail_link (GQueue *queue); GList* g_queue_peek_nth_link (GQueue *queue, - guint n); + guint n); gint g_queue_link_index (GQueue *queue, - GList *link_); + GList *link_); void g_queue_unlink (GQueue *queue, - GList *link_); + GList *link_); void g_queue_delete_link (GQueue *queue, - GList *link_); + GList *link_); G_END_DECLS