docs/gst/gstreamer-sections.txt: Moved the message async delivery private lock and cond to the private section.

Original commit message from CVS:
* docs/gst/gstreamer-sections.txt:
Moved the message async delivery private lock and cond
to the private section.

* gst/gstmessage.c:
* gst/gstmessage.h:
Fixed docs.

ChangeLog

@@ -1,3 +1,13 @@
+2005-11-09  Wim Taymans  <wim@fluendo.com>
+
+	* docs/gst/gstreamer-sections.txt:
+	Moved the message async delivery private lock and cond
+	to the private section.
+
+	* gst/gstmessage.c:
+	* gst/gstmessage.h:
+	Fixed docs.
+
 2005-11-09  Edward Hervey  <edward@fluendo.com>
 
 	* docs/gst/gstreamer-sections.txt:

docs/gst/gstreamer-sections.txt

@@ -961,16 +961,10 @@ gst_iterator_result_get_type
 <TITLE>GstMessage</TITLE>
 GstMessage
 GstMessageType
-GST_MESSAGE_COND
-GST_MESSAGE_GET_LOCK
-GST_MESSAGE_LOCK
-GST_MESSAGE_SIGNAL
 GST_MESSAGE_SRC
 GST_MESSAGE_TIMESTAMP
-GST_MESSAGE_TRACE_NAME
 GST_MESSAGE_TYPE
-GST_MESSAGE_UNLOCK
-GST_MESSAGE_WAIT
+GST_MESSAGE_TRACE_NAME
 gst_message_type_to_quark
 gst_message_type_get_name
 gst_message_copy
@@ -1006,6 +1000,7 @@ gst_message_unref
 <SUBSECTION Standard>
 GstMessageClass
 GST_MESSAGE
+GST_MESSAGE_CAST
 GST_IS_MESSAGE
 GST_TYPE_MESSAGE
 GST_MESSAGE_CLASS
@@ -1015,6 +1010,12 @@ GST_TYPE_MESSAGE_TYPE
 <SUBSECTION Private>
 gst_message_get_type
 gst_message_type_get_type
+GST_MESSAGE_COND
+GST_MESSAGE_GET_LOCK
+GST_MESSAGE_LOCK
+GST_MESSAGE_SIGNAL
+GST_MESSAGE_UNLOCK
+GST_MESSAGE_WAIT
 </SECTION>
 
 

gst/gstmessage.c

@@ -23,7 +23,7 @@
  * SECTION:gstmessage
  * @short_description: Lightweight objects to signal the application of
  *                     pipeline events
- * @see_also: #GstBus,#GstMiniObject
+ * @see_also: #GstBus, #GstMiniObject, #GstElement
  *
  * Messages are implemented as a subclass of #GstMiniObject with a generic
  * #GstStructure as the content. This allows for writing custom messages without
@@ -32,6 +32,20 @@
  *
  * Messages are posted by objects in the pipeline and are passed to the
  * application using the #GstBus.
+
+ * The basic use pattern of posting a message on a #GstBus is as follows:
+ *
+ * <example>
+ * <title>Posting a #GstMessage</title>
+ *   <programlisting>
+ *    gst_bus_post (bus, gst_message_new_eos());
+ *   </programlisting>
+ * </example>
+ *
+ * A #GstElement usually posts messages on the bus provided by the parent
+ * container using gst_element_post_message().
+ *
+ * Last reviewed on 2005-11-09 (0.9.4)
  */
 
 #include <string.h>             /* memcpy */

gst/gstmessage.h

@@ -91,6 +91,11 @@ typedef enum
 #include <gst/gsttaglist.h>
 #include <gst/gststructure.h>
 
+/**
+ * GST_MESSAGE_TRACE_NAME:
+ *
+ * The name used for memory allocation tracing
+ */
 #define GST_MESSAGE_TRACE_NAME	"GstMessage"
 
 #define GST_TYPE_MESSAGE			 (gst_message_get_type())
@@ -99,6 +104,7 @@ typedef enum
 #define GST_MESSAGE_GET_CLASS(obj)               (G_TYPE_INSTANCE_GET_CLASS ((obj), GST_TYPE_MESSAGE, GstMessageClass))
 #define GST_MESSAGE(obj)                         (G_TYPE_CHECK_INSTANCE_CAST ((obj), GST_TYPE_MESSAGE, GstMessage))
 #define GST_MESSAGE_CLASS(klass)                 (G_TYPE_CHECK_CLASS_CAST ((klass), GST_TYPE_MESSAGE, GstMessageClass))
+#define GST_MESSAGE_CAST(obj)                    ((GstMessage*)(obj))
 
 /* the lock is used to handle the synchronous handling of messages,
  * the emiting thread is block until the handling thread processed
@@ -110,15 +116,44 @@ typedef enum
 #define GST_MESSAGE_WAIT(message)	g_cond_wait(GST_MESSAGE_COND(message),GST_MESSAGE_GET_LOCK(message))
 #define GST_MESSAGE_SIGNAL(message)	g_cond_signal(GST_MESSAGE_COND(message))
 
+/**
+ * GST_MESSAGE_TYPE:
+ * @message: a #GstMessage
+ *
+ * Get the #GstMessageType of @message.
+ */
 #define GST_MESSAGE_TYPE(message)	(GST_MESSAGE(message)->type)
+/**
+ * GST_MESSAGE_TIMESTAMP:
+ * @message: a #GstMessage
+ *
+ * Get the timestamp of @message. This is the timestamp when the message
+ * was created.
+ */
 #define GST_MESSAGE_TIMESTAMP(message)	(GST_MESSAGE(message)->timestamp)
+/**
+ * GST_MESSAGE_SRC:
+ * @message: a #GstMessage
+ *
+ * Get the object that posted @message.
+ */
 #define GST_MESSAGE_SRC(message)	(GST_MESSAGE(message)->src)
 
+/**
+ * GstMessage:
+ * @mini_object: the parent structure
+ * @type: the #GstMessageType of the message
+ * @timestamp: the timestamp of the message
+ * @src: the src of the message
+ * @structure: the #GstStructure containing the message info.
+ *
+ * A #GstMessage. 
+ */
 struct _GstMessage
 {
   GstMiniObject mini_object;
 
-  /*< public > *//* with MESSAGE_LOCK */
+  /*< private > *//* with MESSAGE_LOCK */
   GMutex *lock;                 /* lock and cond for async delivery */
   GCond *cond;