lots of new docs and doc fixes

Original commit message from CVS:
* docs/gst/gstreamer-sections.txt:
* gst/gstmessage.c:
* gst/gstmessage.h:
* gst/gstminiobject.c:
* gst/gstminiobject.h:
* gst/gstobject.h:
* gst/gstpad.h:
* gst/gstutils.h:
lots of new docs and doc fixes

ChangeLog

@@ -1,3 +1,14 @@
+2005-10-08  Stefan Kost  <ensonic@users.sf.net>
+	* docs/gst/gstreamer-sections.txt:
+	* gst/gstmessage.c:
+	* gst/gstmessage.h:
+	* gst/gstminiobject.c:
+	* gst/gstminiobject.h:
+	* gst/gstobject.h:
+	* gst/gstpad.h:
+	* gst/gstutils.h:
+	  lots of new docs and doc fixes
+
 2005-10-08  Thomas Vander Stichele  <thomas at apestaart dot org>
 
 	* gst/gstplugin.c: (gst_plugin_finalize), (gst_plugin_load_file):

docs/gst/gstreamer-sections.txt

@@ -754,7 +754,6 @@ gst_index_add_object
 gst_index_add_id
 gst_index_get_assoc_entry
 gst_index_get_assoc_entry_full
-gst_index_entry_get_type
 gst_index_entry_copy
 gst_index_entry_free
 gst_index_entry_assoc_map
@@ -777,6 +776,7 @@ GST_TYPE_INDEX_RESOLVER_METHOD
 gst_index_get_type
 gst_assoc_flags_get_type
 gst_index_certainty_get_type
+gst_index_entry_get_type
 gst_index_entry_type_get_type
 gst_index_flags_get_type
 gst_index_lookup_method_get_type
@@ -1001,7 +1001,6 @@ gst_message_parse_state_changed
 gst_message_parse_tag
 gst_message_parse_warning
 gst_message_ref
-gst_message_type_get_type
 gst_message_unref
 <SUBSECTION Standard>
 GstMessageClass
@@ -1014,6 +1013,7 @@ GST_MESSAGE_GET_CLASS
 GST_TYPE_MESSAGE_TYPE
 <SUBSECTION Private>
 gst_message_get_type
+gst_message_type_get_type
 </SECTION>
 
 
@@ -1854,7 +1854,6 @@ GST_TASK_WAIT
 gst_task_cleanup_all
 gst_task_create
 gst_task_get_state
-gst_task_get_type
 gst_task_join
 gst_task_pause
 gst_task_set_lock

gst/gstmessage.c

@@ -93,6 +93,14 @@ static GstMessageQuarks message_quarks[] = {
   {0, NULL, 0}
 };
 
+/**
+ * gst_message_type_get_name:
+ * @type: the message type
+ *
+ * Get a printable name for the given message type. Do not modify or free.
+ *
+ * Returns: a reference to the static name of the message. 
+ */
 const gchar *
 gst_message_type_get_name (GstMessageType type)
 {
@@ -105,6 +113,14 @@ gst_message_type_get_name (GstMessageType type)
   return "unknown";
 }
 
+/**
+ * gst_message_type_to_quark:
+ * @type: the message type
+ *
+ * Get the unique quark for the given message type.
+ *
+ * Returns: the quark associated with the message type
+ */
 GQuark
 gst_message_type_to_quark (GstMessageType type)
 {
@@ -364,7 +380,7 @@ gst_message_new_tag (GstObject * src, GstTagList * tag_list)
 }
 
 /**
- * gst_message_new_state_change:
+ * gst_message_new_state_changed:
  * @src: The object originating the message.
  * @old: The previous state.
  * @new: The new (current) state.
@@ -536,6 +552,8 @@ gst_message_new_segment_done (GstObject * src, GstClockTime timestamp)
  * Create a new application-typed message. GStreamer will never create these
  * messages; they are a gift from us to you. Enjoy.
  *
+ * Returns: The new application message.
+ *
  * MT safe.
  */
 GstMessage *
@@ -555,6 +573,8 @@ gst_message_new_application (GstObject * src, GstStructure * structure)
  * "the firewire cable was unplugged". The format of the message should be
  * documented in the element's documentation. The structure field can be NULL.
  *
+ * Returns: The new element message.
+ *
  * MT safe.
  */
 GstMessage *
@@ -586,6 +606,7 @@ gst_message_get_structure (GstMessage * message)
 /**
  * gst_message_parse_tag:
  * @message: A valid #GstMessage of type GST_MESSAGE_TAG.
+ * @tag_list: Return location for the tag-list.
  *
  * Extracts the tag list from the GstMessage. The tag list returned in the
  * output argument is a copy; the caller must free it when done.
@@ -715,6 +736,8 @@ gst_message_parse_new_clock (GstMessage * message, GstClock ** clock)
 /**
  * gst_message_parse_error:
  * @message: A valid #GstMessage of type GST_MESSAGE_ERROR.
+ * @gerror: Location for the GError
+ * @debug: Location for the debug message
  *
  * Extracts the GError and debug string from the GstMessage. The values returned
  * in the output arguments are copies; the caller must free them when done.
@@ -745,6 +768,8 @@ gst_message_parse_error (GstMessage * message, GError ** gerror, gchar ** debug)
 /**
  * gst_message_parse_warning:
  * @message: A valid #GstMessage of type GST_MESSAGE_WARNING.
+ * @gerror: Location for the GError
+ * @debug: Location for the debug message
  *
  * Extracts the GError and debug string from the GstMessage. The values returned
  * in the output arguments are copies; the caller must free them when done.
@@ -777,6 +802,7 @@ gst_message_parse_warning (GstMessage * message, GError ** gerror,
 /**
  * gst_message_parse_segment_start:
  * @message: A valid #GstMessage of type GST_MESSAGE_SEGMENT_START.
+ * @timestamp: Result location for the timestamp
  *
  * Extracts the timestamp from the segment start message.
  *
@@ -801,6 +827,7 @@ gst_message_parse_segment_start (GstMessage * message, GstClockTime * timestamp)
 /**
  * gst_message_parse_segment_done:
  * @message: A valid #GstMessage of type GST_MESSAGE_SEGMENT_DONE.
+ * @timestamp: Result location for the timestamp
  *
  * Extracts the timestamp from the segment done message.
  *

gst/gstmessage.h

@@ -142,18 +142,54 @@ const gchar*	gst_message_type_get_name	(GstMessageType type);
 GQuark		gst_message_type_to_quark	(GstMessageType type);
 
 /* refcounting */
+/**
+ * gst_message_ref:
+ * @msg: the message to ref
+ *
+ * Convinience macro to increase the reference count of the message.
+ *
+ * Returns: the refed message.
+ */
 #define         gst_message_ref(msg)		GST_MESSAGE (gst_mini_object_ref (GST_MINI_OBJECT (msg)))
+/**
+ * gst_message_unref:
+ * @msg: the message to unref
+ *
+ * Convinience macro to decrease the reference count of the message, possibly freeing
+ * the it.
+ */
 #define         gst_message_unref(msg)		gst_mini_object_unref (GST_MINI_OBJECT (msg))
 /* copy message */
+/**
+ * gst_message_copy:
+ * @msg: the message to copy
+ *
+ * Creates a copy of the message.
+ *
+ * MT safe
+ *
+ * Returns: the new message.
+ */
 #define         gst_message_copy(msg)		GST_MESSAGE (gst_mini_object_copy (GST_MINI_OBJECT (msg)))
+/**
+ * gst_message_make_writable:
+ * @msg: the message to make writable
+ *
+ * Checks if a message is writable. If not, a writable copy is made and
+ * returned.
+ *
+ * MT safe
+ *
+ * Returns: a message (possibly a duplicate) that it writable.
+ */
 #define         gst_message_make_writable(msg)	GST_MESSAGE (gst_mini_object_make_writable (GST_MINI_OBJECT (msg)))
 
 GstMessage *	gst_message_new_eos 		(GstObject * src);
 GstMessage *	gst_message_new_error 		(GstObject * src, GError * error, gchar * debug);
 GstMessage *	gst_message_new_warning 	(GstObject * src, GError * error, gchar * debug);
 GstMessage *	gst_message_new_tag 		(GstObject * src, GstTagList * tag_list);
-GstMessage *	gst_message_new_state_changed 	(GstObject * src, GstState old_state,
+GstMessage *	gst_message_new_state_changed 	(GstObject * src, GstState old,
-                                                 GstState new_state, GstState pending);
+                                                 GstState new, GstState pending);
 GstMessage *	gst_message_new_clock_provide	(GstObject * src, GstClock *clock, gboolean ready);
 GstMessage *	gst_message_new_clock_lost	(GstObject * src, GstClock *clock);
 GstMessage *	gst_message_new_new_clock	(GstObject * src, GstClock *clock);
@@ -168,8 +204,8 @@ GstMessage *	gst_message_new_custom 		(GstMessageType type,
 void		gst_message_parse_error		(GstMessage *message, GError **gerror, gchar **debug);
 void		gst_message_parse_warning	(GstMessage *message, GError **gerror, gchar **debug);
 void		gst_message_parse_tag		(GstMessage *message, GstTagList **tag_list);
-void		gst_message_parse_state_changed	(GstMessage *message, GstState *old_state,
+void		gst_message_parse_state_changed	(GstMessage *message, GstState *old,
-                                                 GstState *new_state, GstState *pending);
+                                                 GstState *new, GstState *pending);
 void		gst_message_parse_clock_provide (GstMessage *message, GstClock **clock, gboolean *ready);
 void		gst_message_parse_clock_lost	(GstMessage *message, GstClock **clock);
 void		gst_message_parse_new_clock	(GstMessage *message, GstClock **clock);

gst/gstminiobject.c

@@ -208,8 +208,8 @@ gst_mini_object_is_writable (const GstMiniObject * mini_object)
  * gst_mini_object_make_writable:
  * @mini_object: the mini-object to make writable
  *
- * Checks if a mini-object is writable.  If not, a copy is made and
+ * Checks if a mini-object is writable.  If not, a witeable copy is made and
- * the copy is returned.
+ * returned.
  *
  * MT safe
  *

gst/gstminiobject.h

@@ -43,11 +43,44 @@ typedef struct _GstMiniObjectClass GstMiniObjectClass;
 typedef GstMiniObject * (*GstMiniObjectCopyFunction) (const GstMiniObject *);
 typedef void (*GstMiniObjectFinalizeFunction) (GstMiniObject *);
 
+/**
+ * GST_MINI_OBJECT_FLAGS:
+ * @obj: MiniObject to return flags for.
+ *
+ * This macro returns the entire set of flags for the mini-object.
+ */
 #define GST_MINI_OBJECT_FLAGS(obj)  (GST_MINI_OBJECT(obj)->flags)
+/**
+ * GST_MINI_OBJECT_FLAG_IS_SET:
+ * @obj: MiniObject to check for flags.
+ * @flag: Flag to check for
+ *
+ * This macro checks to see if the given flag is set.
+ */
 #define GST_MINI_OBJECT_FLAG_IS_SET(obj,flag)        (GST_MINI_OBJECT_FLAGS(obj) & (flag))
+/**
+ * GST_MINI_OBJECT_FLAG_SET:
+ * @obj: MiniObject to set flag in.
+ * @flag: Flag to set, can by any number of bits in guint32.
+ *
+ * This macro sets the given bits.
+ */
 #define GST_MINI_OBJECT_FLAG_SET(obj,flag)           (GST_MINI_OBJECT_FLAGS (obj) |= (flag))
+/**
+ * GST_MINI_OBJECT_FLAG_UNSET:
+ * @obj: MiniObject to unset flag in.
+ * @flag: Flag to set, must be a single bit in guint32.
+ *
+ * This macro usets the given bits.
+ */
 #define GST_MINI_OBJECT_FLAG_UNSET(obj,flag)         (GST_MINI_OBJECT_FLAGS (obj) &= ~(flag))
 
+/**
+ * GST_VALUE_HOLDS_MINI_OBJECT:
+ * @value: the #GValue to check
+ *
+ * Checks if the given #GValue contains a #GST_TYPE_MINI_OBJECT value.
+ */
 #define GST_VALUE_HOLDS_MINI_OBJECT(value)  (G_VALUE_HOLDS(value, GST_TYPE_MINI_OBJECT))
 
 typedef enum

gst/gstobject.h

@@ -65,7 +65,19 @@ typedef enum
 } GstObjectFlags;
 
 #ifdef GST_HAVE_GLIB_2_8
+/**
+ * GST_OBJECT_REFCOUNT:
+ * @obj: Object get the refcount for.
+ *
+ * Get access to the reference count field of the object. 
+ */
 #define GST_OBJECT_REFCOUNT(obj)                (((GObject*)(obj))->ref_count)
+/**
+ * GST_OBJECT_REFCOUNT_VALUE:
+ * @obj: Object get the refcount value for.
+ *
+ * Get the reference count value of the object. 
+ */
 #define GST_OBJECT_REFCOUNT_VALUE(obj)          GST_OBJECT_REFCOUNT(obj)
 #else
 #define GST_OBJECT_REFCOUNT(obj)                ((GST_OBJECT_CAST(obj))->refcount)

gst/gstpad.h

@@ -437,7 +437,29 @@ GType			gst_pad_get_type			(void);
 GstPad*			gst_pad_new				(const gchar *name, GstPadDirection direction);
 GstPad*			gst_pad_new_from_template		(GstPadTemplate *templ, const gchar *name);
 
+/**
+ * gst_pad_get_name:
+ * @pad: the pad to get the name from
+ *
+ * Returns a copy of the name of the pad.
+ *
+ * Returns: the name of the pad. g_free() after usage.
+ *
+ * MT safe.
+ */
 #define gst_pad_get_name(pad) gst_object_get_name (GST_OBJECT_CAST (pad))
+/**
+ * gst_pad_get_parent:
+ * @pad: the pad to get the parent of
+ *
+ * Returns the parent of @pad. This function increases the refcount
+ * of the parent object so you should gst_object_unref() it after usage.
+ *
+ * Returns: parent of the object, this can be NULL if the pad has no
+ *   parent. unref after usage.
+ *
+ * MT safe.
+ */
 #define gst_pad_get_parent(pad) gst_object_get_parent (GST_OBJECT_CAST (pad))
 
 GstPadDirection		gst_pad_get_direction			(GstPad *pad);

gst/gstutils.h

@@ -202,23 +202,114 @@ GST_BOILERPLATE_FULL (type, type_as_function, parent_type,              \
 #define _GST_GET(__data, __size, __end) \
     (GUINT##__size##_FROM_##__end (* ((guint##__size *) (__data))))
 
+/**
+ * GST_READ_UINT64_BE:
+ * @data: memory location
+ *
+ * Read a 64 bit unsigned integer value in big endian format from the memory buffer.
+ */
 #define GST_READ_UINT64_BE(data)	_GST_GET (data, 64, BE)
+/**
+ * GST_READ_UINT64_LE:
+ * @data: memory location
+ *
+ * Read a 64 bit unsigned integer value in little endian format from the memory buffer.
+ */
 #define GST_READ_UINT64_LE(data)	_GST_GET (data, 64, LE)
+/**
+ * GST_READ_UINT32_BE:
+ * @data: memory location
+ *
+ * Read a 32 bit unsigned integer value in big endian format from the memory buffer.
+ */
 #define GST_READ_UINT32_BE(data)	_GST_GET (data, 32, BE)
+/**
+ * GST_READ_UINT32_LE:
+ * @data: memory location
+ *
+ * Read a 32 bit unsigned integer value in little endian format from the memory buffer.
+ */
 #define GST_READ_UINT32_LE(data)        _GST_GET (data, 32, LE)
+/**
+ * GST_READ_UINT16_BE:
+ * @data: memory location
+ *
+ * Read a 16 bit unsigned integer value in big endian format from the memory buffer.
+ */
 #define GST_READ_UINT16_BE(data)        _GST_GET (data, 16, BE)
+/**
+ * GST_READ_UINT16_LE:
+ * @data: memory location
+ *
+ * Read a 16 bit unsigned integer value in little endian format from the memory buffer.
+ */
 #define GST_READ_UINT16_LE(data)        _GST_GET (data, 16, LE)
+/**
+ * GST_READ_UINT8:
+ * @data: memory location
+ *
+ * Read an 8 bit unsigned integer value from the memory buffer.
+ */
 #define GST_READ_UINT8(data)		(* ((guint8 *) (data)))
 
 #define _GST_PUT(__data, __size, __end, __num) \
     ((* (guint##__size *) (__data)) = GUINT##__size##_TO_##__end (__num))
 
+/**
+ * GST_WRITE_UINT64_BE:
+ * @data: memory location
+ * @num: value to store
+ *
+ * Store a 64 bit unsigned integer value in big endian format into the memory buffer.
+ */
 #define GST_WRITE_UINT64_BE(data, num)	_GST_PUT(data, 64, BE, num)
+/**
+ * GST_WRITE_UINT64_LE:
+ * @data: memory location
+ * @num: value to store
+ *
+ * Store a 64 bit unsigned integer value in little endian format into the memory buffer.
+ */
 #define GST_WRITE_UINT64_LE(data, num)  _GST_PUT(data, 64, LE, num)
+/**
+ * GST_WRITE_UINT32_BE:
+ * @data: memory location
+ * @num: value to store
+ *
+ * Store a 32 bit unsigned integer value in big endian format into the memory buffer.
+ */
 #define GST_WRITE_UINT32_BE(data, num)  _GST_PUT(data, 32, BE, num)
+/**
+ * GST_WRITE_UINT32_LE:
+ * @data: memory location
+ * @num: value to store
+ *
+ * Store a 32 bit unsigned integer value in little endian format into the memory buffer.
+ */
 #define GST_WRITE_UINT32_LE(data, num)  _GST_PUT(data, 32, LE, num)
+/**
+ * GST_WRITE_UINT16_BE:
+ * @data: memory location
+ * @num: value to store
+ *
+ * Store a 16 bit unsigned integer value in big endian format into the memory buffer.
+ */
 #define GST_WRITE_UINT16_BE(data, num)  _GST_PUT(data, 16, BE, num)
+/**
+ * GST_WRITE_UINT16_LE:
+ * @data: memory location
+ * @num: value to store
+ *
+ * Store a 16 bit unsigned integer value in little endian format into the memory buffer.
+ */
 #define GST_WRITE_UINT16_LE(data, num)  _GST_PUT(data, 16, LE, num)
+/**
+ * GST_WRITE_UINT8:
+ * @data: memory location
+ * @num: value to store
+ *
+ * Store an 8 bit unsigned integer value into the memory buffer.
+ */
 #define GST_WRITE_UINT8(data, num)	((* (guint8 *) (data)) = (num))
 
 #else /* GST_HAVE_UNALIGNED_ACCESS */
@@ -319,11 +410,48 @@ GST_BOILERPLATE_FULL (type, type_as_function, parent_type,              \
 
 
 /* Miscellaneous utility macros */
+
+/**
+ * GST_ROUND_UP_2:
+ * @num: value round up
+ *
+ * Make number divideable by two without a rest.
+ */
 #define GST_ROUND_UP_2(num)  (((num)+1)&~1)
+/**
+ * GST_ROUND_UP_4:
+ * @num: value round up
+ *
+ * Make number divideable by four without a rest.
+ */
 #define GST_ROUND_UP_4(num)  (((num)+3)&~3)
+/**
+ * GST_ROUND_UP_8:
+ * @num: value round up
+ *
+ * Make number divideable by eight without a rest.
+ */
 #define GST_ROUND_UP_8(num)  (((num)+7)&~7)
+/**
+ * GST_ROUND_UP_16:
+ * @num: value round up
+ *
+ * Make number divideable by 16 without a rest.
+ */
 #define GST_ROUND_UP_16(num) (((num)+15)&~15)
+/**
+ * GST_ROUND_UP_32:
+ * @num: value round up
+ *
+ * Make number divideable by 32 without a rest.
+ */
 #define GST_ROUND_UP_32(num) (((num)+31)&~31)
+/**
+ * GST_ROUND_UP_64:
+ * @num: value round up
+ *
+ * Make number divideable by 64 without a rest.
+ */
 #define GST_ROUND_UP_64(num) (((num)+63)&~63)
 
 void			gst_object_default_error	(GstObject * source,