more api documentation better error signaling and logging

Original commit message from CVS:
more api documentation
better error signaling and logging

ChangeLog

@@ -1,3 +1,16 @@
+2004-10-13  Stefan Kost  <ensonic@users.sf.net>
+
+	* docs/gst/tmpl/gstobject.sgml:
+	* docs/gst/tmpl/gstplugin.sgml:
+	* docs/gst/tmpl/gstpluginfeature.sgml:
+	* docs/gst/tmpl/gstregistry.sgml:
+	* docs/gst/tmpl/gstversion.sgml:
+	* gst/gstbin.c:
+	  more api documentation
+	* gst/gstplugin.c: (gst_plugin_register_func),
+	(gst_plugin_check_file), (gst_plugin_load_file):
+	  better error signaling and logging
+
 2004-10-11  Ronald S. Bultje  <rbultje@ronald.bitfreak.net>
 
 	* gst/gstqueue.c: (gst_queue_init), (gst_queue_handle_src_query):

docs/gst/tmpl/gstobject.sgml

@@ -13,8 +13,50 @@ very usable on its own.
 </para>
 
 <para>
-GstObject gives us basic refcounting, parenting functionality and locking. 
+GstObject gives us basic refcounting, parenting functionality and locking.
+Most of the function are just extended for special gstreamer needs and can be
+found under the same name in the base class of GstObject which is GObject
+(e.g. g_object_ref becomes gst_object_ref).
 </para>
+
+<para>
+The most interesting difference between GstObject and GObject is the "floating"
+reference count. A GObject is created with a reference count of 1, owned by the
+creator of the GObject. (The owner of a reference is the code section that has
+the right to call gst_object_unref() in order to remove that reference.)
+A GstObject is created with a reference count of 1 also, but it isn't owned by
+anyone; calling gst_object_unref() on the newly-created GtkObject is incorrect.
+Instead, the initial reference count of a GstObject is "floating". The floating
+reference can be removed by anyone at any time, by calling gst_object_sink().
+gst_object_sink() does nothing if an object is already sunk (has no floating
+reference).
+</para>
+<para>
+When you add a GstElement to its parent container, the parent container will do
+this:
+<programlisting>
+  gst_object_ref (GST_OBJECT (child_element));
+  gst_object_sink (GST_OBJECT (child_element));
+</programlisting>
+This means that the container now owns a reference to the child element (since
+it called gst_object_ref()), and the child element has no floating reference.
+</para>
+<para>
+The purpose of the floating reference is to keep the child element alive until
+you add it to a parent container:
+<programlisting>
+   element = gst_element_factory_make (factoryname, name);
+   /* element has one floating reference to keep it alive */
+   gtk_bin_add (GTK_BIN (bin), element);
+   /* element has one non-floating reference owned by the container */
+</programlisting>
+</para>
+<para>
+Another effect of this is, that calling gst_object_unref() on a bin object, will
+also destoy all the GstElement objects in it. The same is true for calling
+gst_bin_remove().
+</para>
+
 <para>
 gst_object_set_name() and gst_object_get_name() are used to set/get the name of the 
 object.

docs/gst/tmpl/gstplugin.sgml

@@ -152,12 +152,13 @@ One would use this macro to define a local plugin that can only be used by the o
 
 <!-- ##### USER_FUNCTION GstPluginFilter ##### -->
 <para>
-
+A function that can be used with e.g. gst_registry_plugin_filter()
+to get a list of plugins that match certain criteria.
 </para>
 
-@plugin: 
+@plugin: the plugin to check
-@user_data: 
+@user_data: the user_data that has been passed on e.g. gst_registry_plugin_filter()
-@Returns: 
+@Returns: TRUE for a positive match, FALSE otherwise
 
 
 <!-- ##### FUNCTION gst_plugin_get_name ##### -->

docs/gst/tmpl/gstpluginfeature.sgml

@@ -38,12 +38,13 @@ Get the name of the feature
 
 <!-- ##### USER_FUNCTION GstPluginFeatureFilter ##### -->
 <para>
-
+A function that can be used with e.g. gst_registry_feature_filter()
+to get a list of pluginfeature that match certain criteria.
 </para>
 
-@feature: 
+@feature: the pluginfeature to check
-@user_data: 
+@user_data: the user_data that has been passed on e.g. gst_registry_feature_filter()
-@Returns: 
+@Returns: TRUE for a positive match, FALSE otherwise
 
 
 <!-- ##### FUNCTION gst_plugin_feature_ensure_loaded ##### -->

docs/gst/tmpl/gstregistry.sgml

@@ -2,11 +2,12 @@
 GstRegistry
 
 <!-- ##### SECTION Short_Description ##### -->
-Abstract base class for management of #GstPlugin objects
+Abstract base class for management of #GstPlugin objects.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-The registry holds the available plugins in the system.
+One registry holds the metadata of a set of plugins.
+All registries build the #GstRegistryPool.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->

docs/gst/tmpl/gstversion.sgml

@@ -2,11 +2,12 @@
 GstVersion
 
 <!-- ##### SECTION Short_Description ##### -->
-GStreamer version macros
+GStreamer version macros.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+Use these macros e.g. when defining own plugins.
+The version macros get defined by including "gst/gst.h".
 </para>
 
 <!-- ##### SECTION See_Also ##### -->

gst/gstbin.c

@@ -509,7 +509,7 @@ gst_bin_add_func (GstBin * bin, GstElement * element)
  * @element: #GstElement to add to bin
  *
  * Adds the given element to the bin.  Sets the element's parent, and thus
- * adds a reference.
+ * takes ownership of the element. An element can only be added to one bin.
  */
 void
 gst_bin_add (GstBin * bin, GstElement * element)

gst/gstplugin.c

@@ -204,6 +204,9 @@ gst_plugin_register_func (GstPlugin * plugin, GModule * module,
     return FALSE;
   }
 
+  if (GST_CAT_DEFAULT)
+    GST_LOG ("plugin \"%s\" looks good", GST_STR_NULL (plugin->filename));
+
   gst_plugin_desc_copy (&plugin->desc, desc);
   plugin->module = module;
 
@@ -423,7 +426,7 @@ gst_plugin_load_file (const gchar * filename, GError ** error)
       plugin, filename);
 
   if (g_module_symbol (module, "plugin_init", &ptr)) {
-    g_print
+    GST_WARNING
         ("plugin %p from file \"%s\" exports a symbol named plugin_init\n",
         plugin, plugin->filename);
     g_set_error (error, GST_PLUGIN_ERROR, GST_PLUGIN_ERROR_NAME_MISMATCH,
@@ -434,6 +437,9 @@ gst_plugin_load_file (const gchar * filename, GError ** error)
   _gst_plugin_fault_handler_setup ();
   _gst_plugin_fault_handler_filename = plugin->filename;
 
+  GST_LOG ("Plugin %p for file \"%s\" prepared, registering...",
+      plugin, filename);
+
   if (gst_plugin_register_func (plugin, module, desc)) {
     /* remove signal handler */
     _gst_plugin_fault_handler_restore ();