added two new functions to the docs documents all undocumented GstXXXFlags completed some incomplete docs

Original commit message from CVS:
* docs/gst/gstreamer-sections.txt:
* gst/base/gstbasesrc.h:
* gst/gstelement.h:
* gst/gstevent.h:
* gst/gstobject.h:
* gst/gstpad.h:
* gst/gstpipeline.c:
* gst/gstpipeline.h:
* gst/gstutils.h:
* gst/gstxml.h:
added two new functions to the docs
documents all undocumented GstXXXFlags
completed some incomplete docs

ChangeLog

@@ -1,3 +1,19 @@
+2005-09-27  Stefan Kost  <ensonic@users.sf.net>
+
+	* docs/gst/gstreamer-sections.txt:
+	* gst/base/gstbasesrc.h:
+	* gst/gstelement.h:
+	* gst/gstevent.h:
+	* gst/gstobject.h:
+	* gst/gstpad.h:
+	* gst/gstpipeline.c:
+	* gst/gstpipeline.h:
+	* gst/gstutils.h:
+	* gst/gstxml.h:
+	  added two new functions to the docs
+		documents all undocumented GstXXXFlags
+		completed some incomplete docs 
+
 2005-09-27  Thomas Vander Stichele  <thomas at apestaart dot org>
 
 	* gst/gstbin.c: (gst_bin_dispose):

docs/gst/gstreamer-sections.txt

@@ -55,6 +55,7 @@ gst_bin_get_by_interface
 gst_bin_iterate_elements
 gst_bin_iterate_recurse
 gst_bin_iterate_sinks
+gst_bin_iterate_sorted
 gst_bin_iterate_all_by_interface
 <SUBSECTION>
 gst_bin_add_many
@@ -882,8 +883,6 @@ gst_debug_level_get_type
 <FILE>gstimplementsinterface</FILE>
 <TITLE>GstImplementsInterface</TITLE>
 GstImplementsInterface
-GST_IMPLEMENTS_INTERFACE_CHECK_INSTANCE_CAST
-GST_IMPLEMENTS_INTERFACE_CHECK_INSTANCE_TYPE
 gst_element_implements_interface
 gst_implements_interface_cast
 gst_implements_interface_check
@@ -895,6 +894,8 @@ GST_IS_IMPLEMENTS_INTERFACE
 GST_IS_IMPLEMENTS_INTERFACE_CLASS
 GST_IMPLEMENTS_INTERFACE_GET_CLASS
 GST_TYPE_IMPLEMENTS_INTERFACE
+GST_IMPLEMENTS_INTERFACE_CHECK_INSTANCE_CAST
+GST_IMPLEMENTS_INTERFACE_CHECK_INSTANCE_TYPE
 <SUBSECTION Private>
 gst_implements_interface_get_type
 </SECTION>
@@ -1082,6 +1083,7 @@ gst_object_set_name_prefix
 gst_object_default_deep_notify
 gst_object_default_error
 gst_object_check_uniqueness
+gst_object_has_ancestor
 gst_object_save_thyself
 gst_object_restore_thyself
 gst_object_ref

gst/base/gstbasesrc.h

@@ -35,6 +35,13 @@ G_BEGIN_DECLS
 #define GST_IS_BASE_SRC(obj)		(G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_BASE_SRC))
 #define GST_IS_BASE_SRC_CLASS(obj)	(G_TYPE_CHECK_CLASS_TYPE((klass),GST_TYPE_BASE_SRC))
 
+/**
+ * GstBaseSrcFlags:
+ * @GST_BASE_SRC_STARTED: has source been started
+ * @GST_BASE_SRC_FLAG_LAST: offset to define more flags
+ *
+ * The #GstElement flags that a basesrc element may have.
+ */
 typedef enum {
   GST_BASE_SRC_STARTED           = GST_ELEMENT_FLAG_LAST,
 

gst/gstelement.h

@@ -387,6 +387,7 @@ GType			gst_element_get_type		(void);
 /**
  * gst_element_set_name:
  * @elem: a #GstElement to set the name of.
+ * @name: the new name
  *
  * Sets the name of the element, getting rid of the old name if there was one.
  */

gst/gstevent.h

@@ -172,6 +172,8 @@ typedef enum {
  * @GST_SEEK_FLAG_SEGMENT: perform a segment seek. After the playback
  *            of the segment completes, no EOS will be emmited but a
  *            SEGMENT_DONE message will be posted on the bus.
+ *
+ * Flags to be used with gst_element_seek()
  */
 typedef enum {
   GST_SEEK_FLAG_NONE		= 0,

gst/gstobject.h

@@ -54,6 +54,7 @@ GST_EXPORT GType _gst_object_type;
  *  not assigned to a bin)
  * @GST_OBJECT_FLAG_LAST: subclasses can add additional flags starting from this flag
  *
+ * The standard flags that an gstobject may have.
  */
 typedef enum
 {
@@ -176,14 +177,20 @@ typedef struct _GstObjectClass GstObjectClass;
 
 /**
  * GstObject:
+ * @refcount: only used ifndef GST_HAVE_GLIB_2_8
+ * @lock: object LOCK
  * @name: The name of the object
+ * @name_prefix: used for debugging
+ * @parent: this object's parent, weak ref
+ * @flags: use GST_OBJECT_IS_XXX macros to access the flags
  *
+ * GStreamer base object class.
  */
 struct _GstObject {
   GObject 	 object;
 
   /*< public >*/
-  gint           refcount;    /* only used ifndef GST_HAVE_GLIB_0_8 */
+  gint           refcount;
 
   /*< public >*/ /* with LOCK */
   GMutex        *lock;        /* object LOCK */

gst/gstpad.h

@@ -125,7 +125,7 @@ typedef gboolean		(*GstPadActivateModeFunction)	(GstPad *pad, gboolean active);
  * 
  * A function that will be called when chaining buffers.
  *
- * 
+ *  Returns: GST_FLOW_OK for success
  */
 typedef GstFlowReturn		(*GstPadChainFunction)		(GstPad *pad, GstBuffer *buffer);
 typedef GstFlowReturn		(*GstPadGetRangeFunction)	(GstPad *pad, guint64 offset,
@@ -252,12 +252,23 @@ typedef enum {
   GST_PAD_SINK
 } GstPadDirection;
 
+/**
+ * GstPadFlags:
+ * @GST_PAD_BLOCKED: is dataflow on a pad blocked
+ * @GST_PAD_FLUSHING: is pad empying buffers
+ * @GST_PAD_IN_GETCAPS: GstPadGetCapsFunction() is running now
+ * @GST_PAD_IN_SETCAPS: GstPadSetCapsFunction() is running now
+ * @GST_PAD_FLAG_LAST: offset to define more flags
+ *
+ * Pad state flags
+ */
 typedef enum {
   GST_PAD_BLOCKED		= GST_OBJECT_FLAG_LAST,
   GST_PAD_FLUSHING,
   GST_PAD_IN_GETCAPS,
   GST_PAD_IN_SETCAPS,
 
+	/* padding */
   GST_PAD_FLAG_LAST		= GST_OBJECT_FLAG_LAST + 8
 } GstPadFlags;
 

gst/gstpipeline.c

@@ -436,7 +436,7 @@ gst_pipeline_get_bus (GstPipeline * pipeline)
 /**
  * gst_pipeline_set_new_stream_time:
  * @pipeline: the pipeline
- * @GstClockTime: the new stream time to set
+ * @time: the new stream time to set
  *
  * Set the new stream time of the pipeline. The stream time is used to
  * set the base time on the elements (see @gst_element_set_base_time())

gst/gstpipeline.h

@@ -38,8 +38,14 @@ G_BEGIN_DECLS
 typedef struct _GstPipeline GstPipeline;
 typedef struct _GstPipelineClass GstPipelineClass;
 
+/**
+ * GstPipelineFlags:
+ * @GST_PIPELINE_FLAG_FIXED_CLOCK: this pipeline works with a fixed clock
+ * @GST_PIPELINE_FLAG_LAST: offset to define more flags
+ *
+ * Pipeline flags
+ */
 typedef enum {
-  /* this pipeline works with a fixed clock */
   GST_PIPELINE_FLAG_FIXED_CLOCK        = GST_BIN_FLAG_LAST,
 
   /* padding */

gst/gstutils.h

@@ -42,11 +42,25 @@ void		gst_print_element_args		(GString *buf, gint indent, GstElement *element);
 /* Macros for defining classes.  Ideas taken from Bonobo, which took theirs
    from Nautilus and GOB. */
 
-/* Define the boilerplate type stuff to reduce typos and code size.  Defines
-   the get_type method and the parent_class static variable.
-   void additional_initializations (GType type) is for initializing interfaces
-   and stuff like that */
-
+/**
+ * GST_BOILERPLATE_FULL:
+ * @type: the name of the type struct
+ * @type_as_function: the prefix for the functions
+ * @parent_type: the parent type struct name
+ * @parent_type_macro: the parent type macro
+ * @additional_initializations: function pointer in the form of 
+ * void additional_initializations (GType type) that can be used for
+ * initializing interfaces and the like
+ *
+ * Define the boilerplate type stuff to reduce typos and code size.  Defines
+ * the get_type method and the parent_class static variable.
+ *
+ * <informalexample>
+ * <programlisting>
+ *   GST_BOILERPLATE_FULL (GstFdSink, gst_fdsink, GstElement, GST_TYPE_ELEMENT, _do_init);
+ * </programlisting>
+ * </informalexample>
+ */
 #define GST_BOILERPLATE_FULL(type, type_as_function, parent_type, parent_type_macro, additional_initializations)	\
 									\
 static void type_as_function ## _base_init     (gpointer      g_class);	\
@@ -87,6 +101,23 @@ type_as_function ## _get_type (void)					\
 }
 
 #define __GST_DO_NOTHING(type)	/* NOP */
+
+/**
+ * GST_BOILERPLATE:
+ * @type: the name of the type struct
+ * @type_as_function: the prefix for the functions
+ * @parent_type: the parent type struct name
+ * @parent_type_macro: the parent type macro
+ *
+ * Define the boilerplate type stuff to reduce typos and code size.  Defines
+ * the get_type method and the parent_class static variable.
+ *
+ * <informalexample>
+ * <programlisting>
+ *   GST_BOILERPLATE (GstFdSink, gst_fdsink, GstElement, GST_TYPE_ELEMENT);
+ * </programlisting>
+ * </informalexample>
+ */
 #define GST_BOILERPLATE(type,type_as_function,parent_type,parent_type_macro)	\
   GST_BOILERPLATE_FULL (type, type_as_function, parent_type, parent_type_macro,	\
       __GST_DO_NOTHING)
@@ -97,6 +128,22 @@ type_as_function ## _get_type (void)					\
  * After this you will need to implement interface_as_function ## _supported
  * and interface_as_function ## _interface_init
  */
+/**
+ * GST_BOILERPLATE_WITH_INTERFACE:
+ * @type: the name of the type struct
+ * @type_as_function: the prefix for the functions
+ * @parent_type: the parent type struct name
+ * @parent_type_as_macro: the parent type macro
+ * @interface_type: the name of the interface type struct
+ * @interface_type_as_macro: the interface type macro
+ * @interface_as_function: the interface function name prefix
+ *
+ * Like GST_BOILERPLATE, but makes the type 1) implement an interface, and 2)
+ * implement GstImplementsInterface for that type.
+ *
+ * After this you will need to implement interface_as_function ## _supported
+ * and interface_as_function ## _interface_init
+ */
 #define GST_BOILERPLATE_WITH_INTERFACE(type, type_as_function,		\
     parent_type, parent_type_as_macro, interface_type,			\
     interface_type_as_macro, interface_as_function)			\

gst/gstxml.h

@@ -42,6 +42,11 @@ G_BEGIN_DECLS
 typedef struct _GstXML GstXML;
 typedef struct _GstXMLClass GstXMLClass;
 
+/**
+ * GstXML:
+ *
+ * XML parser object
+ */
 struct _GstXML {
   GstObject object;
 
@@ -49,6 +54,7 @@ struct _GstXML {
 
   xmlNsPtr ns;
 
+	/*< private >*/
   gpointer _gst_reserved[GST_PADDING];
 };
 

libs/gst/base/gstbasesrc.h

@@ -35,6 +35,13 @@ G_BEGIN_DECLS
 #define GST_IS_BASE_SRC(obj)		(G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_BASE_SRC))
 #define GST_IS_BASE_SRC_CLASS(obj)	(G_TYPE_CHECK_CLASS_TYPE((klass),GST_TYPE_BASE_SRC))
 
+/**
+ * GstBaseSrcFlags:
+ * @GST_BASE_SRC_STARTED: has source been started
+ * @GST_BASE_SRC_FLAG_LAST: offset to define more flags
+ *
+ * The #GstElement flags that a basesrc element may have.
+ */
 typedef enum {
   GST_BASE_SRC_STARTED           = GST_ELEMENT_FLAG_LAST,