Documentation updates.

Original commit message from CVS:
Documentation updates.

docs/gst/gstreamer-docs.sgml

@@ -22,7 +22,7 @@
 <!entity GstCaps SYSTEM "sgml/gstcaps.sgml">
 <!entity GstProps SYSTEM "sgml/gstprops.sgml">
 <!entity GstUtils SYSTEM "sgml/gstutils.sgml">
-<!entity GstXml SYSTEM "sgml/gstxml.sgml">
+<!entity GstXML SYSTEM "sgml/gstxml.sgml">
 <!entity GstQueue SYSTEM "sgml/gstqueue.sgml">
 <!entity GstTypeFind SYSTEM "sgml/gsttypefind.sgml">
 <!entity cothreads SYSTEM "sgml/cothreads.sgml">
@@ -83,7 +83,7 @@ with some more specialized elements.</para>
     &GstType;
     &GstTypeFind;
     &GstUtils;
-    &GstXml;
+    &GstXML;
 
     &cothreads;
   </chapter>

docs/gst/gstreamer-sections.txt

@@ -90,6 +90,7 @@ gst_bin_destroy
 gst_bin_add
 gst_bin_remove
 gst_bin_get_by_name
+gst_bin_get_by_name_recurse_up
 gst_bin_get_list
 gst_bin_set_state_type
 gst_bin_iterate
@@ -188,6 +189,8 @@ GstElementFlags
 GST_ELEMENT_IS_THREAD_SUGGESTED
 GST_ELEMENT_IS_COTHREAD_STOPPING
 GST_ELEMENT_IS_EOS
+GST_ELEMENT_PARENT
+GST_ELEMENT_NAME
 GstElement
 GstElementDetails
 GstElementFactory
@@ -199,6 +202,8 @@ gst_element_set_name
 gst_element_get_name
 gst_element_set_manager
 gst_element_get_manager
+gst_element_set_parent
+gst_element_get_parent
 gst_element_add_pad
 gst_element_get_pad
 gst_element_get_pad_list
@@ -214,7 +219,6 @@ gst_element_set_state
 gst_element_error
 gst_element_get_factory
 gst_element_signal_eos
-gst_element_save_thyself
 gst_element_load_thyself
 gst_elementfactory_new
 gst_elementfactory_destroy
@@ -289,15 +293,23 @@ GST_FLAG_UNSET
 GST_LOCK
 GST_TRYLOCK
 GST_UNLOCK
+GST_GET_LOCK
+GST_OBJECT_PARENT
+GST_OBJECT_NAME
 gst_object_new
 gst_object_set_parent
 gst_object_get_parent
+gst_object_set_name
+gst_object_get_name
 gst_object_unparent
 gst_object_ref
 gst_object_unref
 gst_object_sink
 gst_object_destroy
+gst_object_save_thyself
 gst_object_get_path_string
+gst_class_signal_emit_by_name
+gst_class_signal_connect
 <SUBSECTION Standard>
 gst_object_get_type
 GstObjectClass
@@ -368,7 +380,6 @@ gst_pad_select
 gst_pad_set_eos
 gst_pad_handle_qos
 gst_pad_eos
-gst_pad_save_thyself
 gst_pad_load_and_connect
 
 GstRealPad
@@ -651,10 +662,12 @@ gst_util_dump_mem
 
 <SECTION>
 <FILE>gstxml</FILE>
-<TITLE>GstXml</TITLE>
+<TITLE>GstXML</TITLE>
 GstXML
 gst_xml_new
-gst_xml_new_from_memory
+gst_xml_parse_doc
+gst_xml_parse_memory
+gst_xml_parse_file
 gst_xml_write
 gst_xml_get_element
 gst_xml_get_topelements

docs/gst/gstreamer.hierarchy

@@ -1,5 +1,6 @@
 GtkObject
   GstObject
+    GstXML
     GstElement
       GstBin
         GstPipeline
@@ -20,3 +21,4 @@ GtkObject
       GstQueue
       GstTypeFind
     GstPad
+  GstSignalObject

docs/gst/gstreamer.types.in

@@ -4,6 +4,7 @@
 #include <libs/colorspace/gstcolorspace.h>
 
 gst_object_get_type
+gst_xml_get_type
 gst_element_get_type
 gst_bin_get_type
 gst_pipeline_get_type

docs/gst/tmpl/gstbin.sgml

@@ -77,6 +77,16 @@ Flags for a bin.
 @Returns: 
 
 
+<!-- ##### FUNCTION gst_bin_get_by_name_recurse_up ##### -->
+<para>
+
+</para>
+
+@bin: 
+@name: 
+@Returns: 
+
+
 <!-- ##### FUNCTION gst_bin_get_list ##### -->
 <para>
 

docs/gst/tmpl/gstelement.sgml

@@ -152,10 +152,26 @@ Queries whether the cothread holding this element needs to be stopped.
 
 <!-- ##### MACRO GST_ELEMENT_IS_EOS ##### -->
 <para>
-
+Query wether this element is in the End Of Stream state.
 </para>
 
-@obj: 
+@obj: The element to query
+
+
+<!-- ##### MACRO GST_ELEMENT_PARENT ##### -->
+<para>
+Get the parent object of this element.
+</para>
+
+@obj: The element to query
+
+
+<!-- ##### MACRO GST_ELEMENT_NAME ##### -->
+<para>
+Get the name of this element.
+</para>
+
+@obj: The element to query
 
 
 <!-- ##### STRUCT GstElement ##### -->
@@ -261,6 +277,24 @@ circumstances.
 @Returns: 
 
 
+<!-- ##### FUNCTION gst_element_set_parent ##### -->
+<para>
+
+</para>
+
+@element: 
+@parent: 
+
+
+<!-- ##### FUNCTION gst_element_get_parent ##### -->
+<para>
+
+</para>
+
+@element: 
+@Returns: 
+
+
 <!-- ##### FUNCTION gst_element_add_pad ##### -->
 <para>
 

docs/gst/tmpl/gstobject.sgml

@@ -99,6 +99,30 @@ This macro releases a lock on the object.
 @obj: Object to unlock.
 
 
+<!-- ##### MACRO GST_GET_LOCK ##### -->
+<para>
+
+</para>
+
+@obj: 
+
+
+<!-- ##### MACRO GST_OBJECT_PARENT ##### -->
+<para>
+
+</para>
+
+@obj: 
+
+
+<!-- ##### MACRO GST_OBJECT_NAME ##### -->
+<para>
+
+</para>
+
+@obj: 
+
+
 <!-- ##### FUNCTION gst_object_new ##### -->
 <para>
 
@@ -125,6 +149,24 @@ This macro releases a lock on the object.
 @Returns: 
 
 
+<!-- ##### FUNCTION gst_object_set_name ##### -->
+<para>
+
+</para>
+
+@object: 
+@name: 
+
+
+<!-- ##### FUNCTION gst_object_get_name ##### -->
+<para>
+
+</para>
+
+@object: 
+@Returns: 
+
+
 <!-- ##### FUNCTION gst_object_unparent ##### -->
 <para>
 
@@ -165,6 +207,16 @@ This macro releases a lock on the object.
 @object: the object
 
 
+<!-- ##### FUNCTION gst_object_save_thyself ##### -->
+<para>
+
+</para>
+
+@object: 
+@parent: 
+@Returns: 
+
+
 <!-- ##### FUNCTION gst_object_get_path_string ##### -->
 <para>
 
@@ -174,6 +226,28 @@ This macro releases a lock on the object.
 @Returns: 
 
 
+<!-- ##### FUNCTION gst_class_signal_emit_by_name ##### -->
+<para>
+
+</para>
+
+@object: 
+@name: 
+@self: 
+
+
+<!-- ##### FUNCTION gst_class_signal_connect ##### -->
+<para>
+
+</para>
+
+@klass: 
+@name: 
+@func: 
+@func_data: 
+@Returns: 
+
+
 <!-- ##### SIGNAL GstObject::parent-set ##### -->
 <para>
 
@@ -182,3 +256,12 @@ This macro releases a lock on the object.
 @gstobject: the object which received the signal.
 @arg1: the new parent
 
+<!-- ##### SIGNAL GstObject::object-saved ##### -->
+<para>
+Is trigered whenever a new object is saved to XML. You can connect to
+this signal to insert custom XML tags into the core XML.
+</para>
+
+@gstobject: the object which received the signal.
+@arg1: the xmlNodePtr of the parent node
+

docs/gst/tmpl/gstreamer-unused.sgml

@@ -217,13 +217,6 @@ the stream.
 </para>
 
 
-<!-- ##### MACRO GST_SINESRC ##### -->
-<para>
-
-</para>
-
-@obj: 
-
 <!-- ##### FUNCTION gst_object_get_type ##### -->
 <para>
 
@@ -231,6 +224,13 @@ the stream.
 
 @Returns: 
 
+<!-- ##### MACRO GST_SINESRC ##### -->
+<para>
+
+</para>
+
+@obj: 
+
 <!-- ##### SECTION ./tmpl/plugin.sgml:Long_Description ##### -->
 <para>
 
@@ -691,6 +691,14 @@ on its own.
 
 @obj: 
 
+<!-- ##### SIGNAL GstXML::object-loaded ##### -->
+<para>
+Is trigered whenever the state of an element changes
+</para>
+
+@gstelement: the object which received the signal.
+@arg1: the new state of the object
+
 <!-- ##### SECTION ./tmpl/gstgetbits.sgml:Title ##### -->
 GstGetbits
 

docs/gst/tmpl/gstxml.sgml

@@ -20,9 +20,6 @@ All GstElements can be serialized to an XML presentation and subsequently loaded
 
 </para>
 
-@object: 
-@topelements: 
-@ns: 
 
 <!-- ##### FUNCTION gst_xml_new ##### -->
 <para>
@@ -30,9 +27,40 @@ All GstElements can be serialized to an XML presentation and subsequently loaded
 </para>
 
 @Returns: 
-<!-- # Unused Parameters # -->
+
+
+<!-- ##### FUNCTION gst_xml_parse_doc ##### -->
+<para>
+
+</para>
+
+@xml: 
+@doc: 
+@root: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gst_xml_parse_memory ##### -->
+<para>
+
+</para>
+
+@xml: 
+@buffer: 
+@size: 
+@root: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gst_xml_parse_file ##### -->
+<para>
+
+</para>
+
+@xml: 
 @fname: 
 @root: 
+@Returns: 
 
 
 <!-- ##### FUNCTION gst_xml_write ##### -->

gst/gstelement.c

@@ -186,7 +186,7 @@ gst_element_get_name (GstElement *element)
 /**
  * gst_element_set_parent:
  * @element: GstElement to set parent of
- * @name: new parent of the object
+ * @parent: new parent of the object
  *
  * Set the parent of the element.
  */
@@ -917,8 +917,7 @@ gst_element_save_thyself (GstObject *object,
 /**
  * gst_element_load_thyself:
  * @self: the xml node
- * @elements: a hashtable to store the elements in. This is used
+ * @parent: the parent of this object when it's loaded
- *    to resolve inter element dependecies during the loading.
  *
  * Load the element from the XML description
  *

gst/gstobject.c

@@ -478,6 +478,17 @@ gst_signal_object_init (GstSignalObject *object)
 {
 }
 
+/**
+ * gst_class_signal_connect
+ * @klass: the GstObjectClass to attach the signal to
+ * @name: the name of the signal to attach to
+ * @func: the signal function
+ * @func_data: a pointer to user data
+ *
+ * Connect to a class signal.
+ *
+ * Returns: the signal id.
+ */
 guint
 gst_class_signal_connect (GstObjectClass *klass,
 			  const gchar    *name,
@@ -487,6 +498,14 @@ gst_class_signal_connect (GstObjectClass *klass,
   return gtk_signal_connect (klass->signal_object, name, func, func_data);
 }
 
+/**
+ * gst_class_signal_emit_by_name:
+ * @object: the object that sends the signal
+ * @name: the name of the signal to emit
+ * @self: data for the signal
+ *
+ * emits the named class signal.
+ */
 void
 gst_class_signal_emit_by_name (GstObject *object,
 	                       const gchar *name,

gst/gstxml.c

@@ -124,6 +124,17 @@ gst_xml_write (GstElement *element)
   return doc;
 }
 
+/**
+ * gst_xml_parse_doc:
+ * @xml: a pointer to a GstXML object
+ * @doc: a pointer to an xml document to parse
+ * @root: The name of the root object to build
+ *
+ * Fills the GstXML object with the elements from the
+ * xmlDocPtr.
+ *
+ * Returns: TRUE on success, FALSE otherwise
+ */
 gboolean
 gst_xml_parse_doc (GstXML *xml, xmlDocPtr doc, const guchar *root)
 {
@@ -170,16 +181,15 @@ gst_xml_parse_doc (GstXML *xml, xmlDocPtr doc, const guchar *root)
 
 /**
  * gst_xml_parse_file:
+ * @xml: a pointer to a GstXML object
  * @fname: The filename with the xml description
  * @root: The name of the root object to build
  *
- * Creates a new GstXML object (and the corresponding elements) from
+ * Fills the GstXML object with the corresponding elements from
  * the XML file fname. Optionally it will only build the element from
  * the element node root (if it is not NULL). This feature is useful
  * if you only want to build a specific element from an XML file
- * but not the pipeline it is embedded in. Note also that the XML parse
+ * but not the pipeline it is embedded in.
- * tree is cached to speed up creating another GstXML object for
- * the same file
  *
  * Returns: TRUE on success, FALSE otherwise
  */
@@ -202,14 +212,15 @@ gst_xml_parse_file (GstXML *xml, const guchar *fname, const guchar *root)
 
 /**
  * gst_xml_parse_memory:
+ * @xml: a pointer to a GstXML object
  * @buffer: a pointer to the in memory XML buffer
  * @size: the size of the buffer
  * @root: the name of the root objects to build
  *
- * Creates a new GstXML object (and the corresponding elements) from
+ * Fills the GstXML object with the corresponding elements from
  * an in memory XML buffer.
  *
- * Returns: a pointer to a new GstXML object
+ * Returns: TRUE on success
  */
 gboolean
 gst_xml_parse_memory (GstXML *xml, guchar *buffer, guint size, const gchar *root)

gst/gstxml.h

@@ -52,9 +52,6 @@ extern "C" {
 typedef struct _GstXML GstXML;
 typedef struct _GstXMLClass GstXMLClass;
 
-typedef void (*GstXMLObjectLoadedCallback)	(GstXML *xml, GstObject *object, xmlNodePtr self);
-typedef void (*GstXMLObjectSavedCallback)	(GstXML *xml, GstObject *object, xmlNodePtr self);
-
 struct _GstXML {
   GstObject object;
 
@@ -87,9 +84,6 @@ gboolean	gst_xml_parse_memory	(GstXML *xml, guchar *buffer, guint size, const gc
 GstElement*	gst_xml_get_element	(GstXML *xml, const guchar *name);
 GList*		gst_xml_get_topelements (GstXML *xml);
 
-void		gst_xml_connect_object_loaded	(GstXML *xml, GstXMLObjectLoadedCallback *callback, gpointer data);
-void		gst_xml_connect_object_saved	(GstXML *xml, GstXMLObjectSavedCallback *callback, gpointer data);
-
 #ifdef __cplusplus
 }
 #endif /* __cplusplus */