doc updates

Original commit message from CVS:

* docs/README:
* docs/gst/gstreamer-sections.txt:
* gst/gstbin.c:
doc updates
* gst/gstregistry.c: (gst_registry_scan_path_level):
fix for a nasty little missed situation where an installed plug-in
which was in the cache did not get overridden by an uninstalled one
which was earlier in the plugin path because the newly created plugin
for the uninstalled one (not in the registry) didn't get its
->registered set to TRUE

ChangeLog

@@ -1,3 +1,16 @@
+2005-11-02  Thomas Vander Stichele  <thomas at apestaart dot org>
+
+	* docs/README:
+	* docs/gst/gstreamer-sections.txt:
+	* gst/gstbin.c:
+	  doc updates
+	* gst/gstregistry.c: (gst_registry_scan_path_level):
+	  fix for a nasty little missed situation where an installed plug-in
+	  which was in the cache did not get overridden by an uninstalled one
+	  which was earlier in the plugin path because the newly created plugin
+	  for the uninstalled one (not in the registry) didn't get its
+	  ->registered set to TRUE
+
 2005-11-02  Tim-Philipp Müller  <tim at centricular dot net>
 
 	* gst/base/gstcollectpads.c: (gst_collectpads_set_function),

docs/README

@@ -199,7 +199,8 @@ STYLE GUIDE FOR GTK-DOC
     "Caller owns returned value" for other types (iterators, ..)
   - we do this because, in contrast with GLib/GTK, we are more explicit
     about threadsafety and related issues
-
+- link to signals from the description like this:
+  * The <link linkend="GstBin-element-added">element-added</link> signal
 - the bottom of the description should say when the doc was last reviewed
   (version and date)
    * Last reviewed on 2005-10-28 (0.9.4)

docs/gst/gstreamer-sections.txt

@@ -37,11 +37,7 @@ thread_list
 <FILE>gstbin</FILE>
 <TITLE>GstBin</TITLE>
 GstBin
-GstBinFlags
-
-GST_BIN_CHILDREN
-GST_BIN_CHILDREN_COOKIE
-GST_BIN_NUMCHILDREN
+GstBinClass
 
 gst_bin_new
 gst_bin_add
@@ -56,12 +52,19 @@ gst_bin_iterate_recurse
 gst_bin_iterate_sinks
 gst_bin_iterate_sorted
 gst_bin_iterate_all_by_interface
+
 <SUBSECTION>
 gst_bin_add_many
 gst_bin_remove_many
 
+<SUBSECTION>
+GstBinFlags
+
+GST_BIN_CHILDREN
+GST_BIN_CHILDREN_COOKIE
+GST_BIN_NUMCHILDREN
+
 <SUBSECTION Standard>
-GstBinClass
 GST_BIN
 GST_IS_BIN
 GST_TYPE_BIN

gst/gstbin.c

@@ -25,7 +25,7 @@
 
 /**
  * SECTION:gstbin
- * @short_description: Base class for elements that contain other elements
+ * @short_description: Base class and element that can contain other elements
  *
  * GstBin is an element that can contain other elements, allowing them to be
  * managed as a group.
@@ -49,41 +49,61 @@
  * gst_bin_iterate_elements(). Various other iterators exist to retrieve the
  * elements in a bin.
  *
- * The "element_added" signal is fired whenever a new element is added to the
- * bin. Likewise the "element_removed" signal is fired whenever an element is
- * removed from the bin.
+ * gst_object_unref() is used to drop your reference to the bin.
  *
- * A GstBin internally interceps all #GstMessage posted by its children and
+ * The <link linkend="GstBin-element-added">element-added</link> signal is
+ * fired whenever a new element is added to the bin. Likewise the <link
+ * linkend="GstBin-element-removed">element-removed</link> signal is fired
+ * whenever an element is removed from the bin.
+ *
+ * <refsect2><title>Notes</title>
+ * <para>
  * A GstBin internally intercepts every #GstMessage posted by its children and
- * implements the following default behaviour for each of them.
- *
- *   GST_MESSAGE_EOS: This message is only posted by sinks
- *     in the PLAYING state. If all sinks posted the EOS message, this bin
- *     will post and EOS message upwards.
- *
- *   GST_MESSAGE_SEGMENT_START: just collected and never forwarded upwards.
+ * implements the following default behaviour for each of them:
+ * <variablelist>
+ *   <varlistentry>
+ *     <term>GST_MESSAGE_EOS</term>
+ *     <listitem><para>This message is only posted by sinks in the PLAYING
+ *     state. If all sinks posted the EOS message, this bin will post and EOS
+ *     message upwards.</para></listitem>
+ *   </varlistentry>
+ *   <varlistentry>
+ *     <term>GST_MESSAGE_SEGMENT_START</term>
+ *     <listitem><para>just collected and never forwarded upwards.
  *     The messages are used to decide when all elements have completed playback
- *     of their segment.
- *
- *   GST_MESSAGE_SEGMENT_DONE: Is posted by GstBin when all elements that posted
- *     a SEGMENT_START have posted a SEGMENT_DONE.
- *
- *   OTHERS: posted upwards.
+ *     of their segment.</para></listitem>
+ *   </varlistentry>
+ *   <varlistentry>
+ *     <term>GST_MESSAGE_SEGMENT_DONE</term>
+ *     <listitem><para> Is posted by GstBin when all elements that posted
+ *     a SEGMENT_START have posted a SEGMENT_DONE.</para></listitem>
+ *   </varlistentry>
+ *   <varlistentry>
+ *     <term>OTHERS</term>
+ *     <listitem><para> posted upwards.</para></listitem>
+ *   </varlistentry>
+ * </variablelist>
  *
  * A GstBin implements the following default behaviour for answering to a
  * #GstQuery:
- *
- *   GST_QUERY_DURATION: If the query has been asked before with the same
- *           format, use the cached previous value. If no previous value
- *           was cached, the query is sent to all sink elements in the bin
- *           and the MAXIMUM of all values is returned and cached. If no
- *           sinks are available in the bin, the query fails.
- *
- *   OTHERS: the query is forwarded to all sink elements, the result of the
- *           first sink that answers the query successfully is returned. If
- *           no sink is in the bin, the query fails.
- *
- * gst_object_unref() is used to drop your reference to the bin.
+ * <variablelist>
+ *   <varlistentry>
+ *     <term>GST_QUERY_DURATION</term>
+ *     <listitem><para>If the query has been asked before with the same format,
+ *     use the cached previous value. If no previous value was cached, the
+ *     query is sent to all sink elements in the bin and the MAXIMUM of all
+ *     values is returned and cached. If no sinks are available in the bin, the
+ *     query fails.</para></listitem>
+ *   </varlistentry>
+ *   <varlistentry>
+ *     <term>OTHERS</term>
+ *     <listitem><para>the query is forwarded to all sink elements, the result
+ *     of the first sink that answers the query successfully is returned. If no
+ *     sink is in the bin, the query fails.</para></listitem>
+ *   </varlistentry>
+ * </variablelist>
+ * </para>
+ * </refsect2>
  *
  * Last reviewed on 2005-10-28 (0.9.4)
  */

gst/gstregistry.c

@@ -709,11 +709,12 @@ gst_registry_scan_path_level (GstRegistry * registry, const gchar * path,
         gst_object_unref (plugin);
         continue;
       }
-      plugin->registered = TRUE;
       if (plugin->file_mtime == file_status.st_mtime &&
           plugin->file_size == file_status.st_size) {
         GST_DEBUG_OBJECT (registry, "file %s cached", filename);
         plugin->flags &= ~GST_PLUGIN_FLAG_CACHED;
+        GST_DEBUG_OBJECT (registry, "marking plugin %p as registered", plugin);
+        plugin->registered = TRUE;
       } else {
         GST_INFO_OBJECT (registry, "cached info for %s is stale", filename);
         GST_DEBUG_OBJECT (registry, "mtime %ld != %ld or size %"
@@ -722,8 +723,12 @@ gst_registry_scan_path_level (GstRegistry * registry, const gchar * path,
             plugin->file_size, file_status.st_size);
         gst_registry_remove_plugin (gst_registry_get_default (), plugin);
         newplugin = gst_plugin_load_file (filename, NULL);
-        if (newplugin)
+        if (newplugin) {
+          GST_DEBUG_OBJECT (registry, "marking new plugin %p as registered",
+              newplugin);
+          newplugin->registered = TRUE;
           gst_object_unref (newplugin);
+        }
       }
       gst_object_unref (plugin);