Move GAsyncQueue docs inline

docs/reference/glib/tmpl/async_queues.sgml

@@ -2,60 +2,11 @@
 Asynchronous Queues
 
 <!-- ##### SECTION Short_Description ##### -->
-asynchronous communication between threads
+
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-Often you need to communicate between different threads. In general
-it's safer not to do this by shared memory, but by explicit message
-passing. These messages only make sense asynchronously for
-multi-threaded applications though, as a synchronous operation could as
-well be done in the same thread.
-</para>
 
-<para>
-Asynchronous queues are an exception from most other GLib data
-structures, as they can be used simultaneously from multiple threads
-without explicit locking and they bring their own builtin reference
-counting. This is because the nature of an asynchronous queue is that
-it will always be used by at least 2 concurrent threads.
-</para>
-
-<para>
-For using an asynchronous queue you first have to create one with
-g_async_queue_new(). A newly-created queue will get the reference
-count 1. Whenever another thread is creating a new reference of (that
-is, pointer to) the queue, it has to increase the reference count
-(using g_async_queue_ref()). Also, before removing this reference, the
-reference count has to be decreased (using
-g_async_queue_unref()). After that the queue might no longer exist so
-you must not access it after that point.
-</para>
-
-<para>
-A thread, which wants to send a message to that queue simply calls
-g_async_queue_push() to push the message to the queue.
-</para>
-
-<para>
-A thread, which is expecting messages from an asynchronous queue
-simply calls g_async_queue_pop() for that queue. If no message is
-available in the queue at that point, the thread is now put to sleep
-until a message arrives. The message will be removed from the queue
-and returned. The functions g_async_queue_try_pop() and
-g_async_queue_timed_pop() can be used to only check for the presence
-of messages or to only wait a certain time for messages respectively.
-</para>
-
-<para>
-For almost every function there exist two variants, one that locks the
-queue and one that doesn't. That way you can hold the queue lock
-(acquire it with g_async_queue_lock() and release it with
-g_async_queue_unlock()) over multiple queue accessing
-instructions. This can be necessary to ensure the integrity of the
-queue, but should only be used when really necessary, as it can make
-your life harder if used unwisely. Normally you should only use the
-locking function variants (those without the suffix _unlocked)
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
@@ -71,9 +22,7 @@ locking function variants (those without the suffix _unlocked)
 
 <!-- ##### STRUCT GAsyncQueue ##### -->
 <para>
-The #GAsyncQueue struct is an opaque data structure, which represents
+
-an asynchronous queue. It should only be accessed through the
-<function>g_async_queue_*</function> functions.
 </para>
 
 

glib/gasyncqueue.c

@@ -34,7 +34,60 @@
 #include "gthread.h"
 
 
+/**
+ * SECTION: async_queues
+ * @title: Asynchronous Queues
+ * @short_description: asynchronous communication between threads
+ *
+ * Often you need to communicate between different threads. In general
+ * it's safer not to do this by shared memory, but by explicit message
+ * passing. These messages only make sense asynchronously for
+ * multi-threaded applications though, as a synchronous operation could
+ * as well be done in the same thread.
+ *
+ * Asynchronous queues are an exception from most other GLib data
+ * structures, as they can be used simultaneously from multiple threads
+ * without explicit locking and they bring their own builtin reference
+ * counting. This is because the nature of an asynchronous queue is that
+ * it will always be used by at least 2 concurrent threads.
+ *
+ * For using an asynchronous queue you first have to create one with
+ * g_async_queue_new(). A newly-created queue will get the reference
+ * count 1. Whenever another thread is creating a new reference of (that
+ * is, pointer to) the queue, it has to increase the reference count
+ * (using g_async_queue_ref()). Also, before removing this reference,
+ * the reference count has to be decreased (using g_async_queue_unref()).
+ * After that the queue might no longer exist so you must not access
+ * it after that point.
+ *
+ * A thread, which wants to send a message to that queue simply calls
+ * g_async_queue_push() to push the message to the queue.
+ *
+ * A thread, which is expecting messages from an asynchronous queue
+ * simply calls g_async_queue_pop() for that queue. If no message is
+ * available in the queue at that point, the thread is now put to sleep
+ * until a message arrives. The message will be removed from the queue
+ * and returned. The functions g_async_queue_try_pop() and
+ * g_async_queue_timed_pop() can be used to only check for the presence
+ * of messages or to only wait a certain time for messages respectively.
+ *
+ * For almost every function there exist two variants, one that locks
+ * the queue and one that doesn't. That way you can hold the queue lock
+ * (acquire it with g_async_queue_lock() and release it with
+ * g_async_queue_unlock()) over multiple queue accessing instructions.
+ * This can be necessary to ensure the integrity of the queue, but should
+ * only be used when really necessary, as it can make your life harder
+ * if used unwisely. Normally you should only use the locking function
+ * variants (those without the suffix _unlocked)
+ */
 
+/**
+ * GAsyncQueue:
+ *
+ * The GAsyncQueue struct is an opaque data structure, which represents
+ * an asynchronous queue. It should only be accessed through the
+ * <function>g_async_queue_*</function> functions.
+ */
 struct _GAsyncQueue
 {
   GMutex *mutex;