Move GQueue docs inline

diff --git a/glib/gqueue.c b/glib/gqueue.c
index 2f90d6b..e6bf411 100644 (file)
--- 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 <link linkend="glib-Type-Conversion-Macros">Type
+ * Conversion Macros</link>, 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 345d2c7..591a09a 100644 (file)
--- 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
+ * <link linkend="glib-Double-ended-Queues">Queue</link>.
+ */
 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