more api documentation better error signaling and logging

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

diff --git a/ChangeLog b/ChangeLog
index b0729bd529644747666e6869ea4fb6ff2070338d..6ed300a1951e19d2fca013e88dbf08a08adaedd3 100644 (file)
--- a/ChangeLog
+++ b/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):

diff --git a/docs/gst/tmpl/gstobject.sgml b/docs/gst/tmpl/gstobject.sgml
index d5c09f5047e763ed603fe45539356d4c924f9b4f..2c60d982a45f48ea97d56cfe09e3533bd4f4d189 100644 (file)
--- a/docs/gst/tmpl/gstobject.sgml
+++ b/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.

diff --git a/docs/gst/tmpl/gstplugin.sgml b/docs/gst/tmpl/gstplugin.sgml
index e042b50593c446cbaa69559e285b55453610423c..3f3ea073f34dc269572c03372e9eb5b0b7ff6b5d 100644 (file)
--- a/docs/gst/tmpl/gstplugin.sgml
+++ b/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: 
-@user_data: 
-@Returns: 
+@plugin: the plugin to check
+@user_data: the user_data that has been passed on e.g. gst_registry_plugin_filter()
+@Returns: TRUE for a positive match, FALSE otherwise
 
 
 <!-- ##### FUNCTION gst_plugin_get_name ##### -->

diff --git a/docs/gst/tmpl/gstpluginfeature.sgml b/docs/gst/tmpl/gstpluginfeature.sgml
index 49762e7dcd33d86653802f5db2163e9310adfdb3..63952932fcc83b1494fb1d110cf3f90f8c8a18b5 100644 (file)
--- a/docs/gst/tmpl/gstpluginfeature.sgml
+++ b/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: 
-@user_data: 
-@Returns: 
+@feature: the pluginfeature to check
+@user_data: the user_data that has been passed on e.g. gst_registry_feature_filter()
+@Returns: TRUE for a positive match, FALSE otherwise
 
 
 <!-- ##### FUNCTION gst_plugin_feature_ensure_loaded ##### -->

diff --git a/docs/gst/tmpl/gstregistry.sgml b/docs/gst/tmpl/gstregistry.sgml
index c99c23dc390e3a6f25154eeb9369699fbf935262..ac1a7336e2bdf64979db78092560e1ebae83d904 100644 (file)
--- a/docs/gst/tmpl/gstregistry.sgml
+++ b/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 ##### -->

diff --git a/docs/gst/tmpl/gstversion.sgml b/docs/gst/tmpl/gstversion.sgml
index 6c8425e565bf26ddca70cdc70ac22220a8cd8662..d6bcdfcef2c0d9b40f980473dbc19e2f98dadbd5 100644 (file)
--- a/docs/gst/tmpl/gstversion.sgml
+++ b/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 ##### -->

diff --git a/gst/gstbin.c b/gst/gstbin.c
index 21fc89672faaf561f983f7e77357f16973416f60..c6078ad2efee9f6f6b8780d42e9dfed65607d875 100644 (file)
--- a/gst/gstbin.c
+++ b/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)

diff --git a/gst/gstplugin.c b/gst/gstplugin.c
index 170e1bac5bdf10cea17918ead6669c3971ec2d12..a3b38fc6091f5ad5c91033e44c7fbd35a13107af 100644 (file)
--- a/gst/gstplugin.c
+++ b/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 ();