various doc updates

Original commit message from CVS:

* docs/README:
* gst/gstpad.c: (gst_pad_class_init), (gst_pad_chain):
* gst/gstpluginfeature.c:
* gst/gstutils.c:
various doc updates
* gst/base/gstbasesink.c: (gst_base_sink_handle_object):
change an assert into an error until it gets fixed properly

ChangeLog

@@ -1,3 +1,13 @@
+2005-09-23  Thomas Vander Stichele  <thomas at apestaart dot org>
+
+	* docs/README:
+	* gst/gstpad.c: (gst_pad_class_init), (gst_pad_chain):
+	* gst/gstpluginfeature.c:
+	* gst/gstutils.c:
+	  various doc updates
+	* gst/base/gstbasesink.c: (gst_base_sink_handle_object):
+	  change an assert into an error until it gets fixed properly
+
 2005-09-23  Stefan Kost  <ensonic@users.sf.net>
 
 	* docs/gst/gstreamer-sections.txt:

docs/README

@@ -204,6 +204,7 @@ in the various plugin packages.
 - template can be copied from gst-plugins-base
 - to add an element to be documented:
   - add an include href in the Elements chapter for the element
+    in the main .sgml
   - add a section for it in -sections.txt with
       <FILE>element-(element)</FILE>
       <TITLE>(element)</TITLE>
@@ -232,12 +233,19 @@ in the various plugin packages.
     make clean
     make inspect-update
     make
+  - examples will only show up using gtk-doc 1.4 or later - it relies on
+    merging stuff from .sgml with inline docs.  We might want to change
+    this to only get stuff from the source.
 
 - to add a plugin to be documented:
   - make sure inspect/ has generated a .xml file for it
   - add it to CVS
   - add an include in -docs.sgml in the Plugins list for that plugin
 
+- possible errors:
+  "multiple constraints for linkend ID": check if each section in
+  -sections.txt actually starts and ends with <SECTION> and </SECTION>
+
 RANDOM THINGS I'VE LEARNED
 ==========================
 

gst/base/gstbasesink.c

@@ -650,9 +650,16 @@ gst_base_sink_handle_object (GstBaseSink * basesink, GstPad * pad,
     if (!basesink->need_preroll)
       goto no_preroll;
 
+
     length = basesink->preroll_queued;
 
-    g_assert (length == 1);
+    /* FIXME: a pad probe could have made us lose the buffer, according
+     * to one of the python tests */
+    if (length == 0) {
+      GST_ERROR_OBJECT (basesink,
+          "preroll_queued dropped from 1 to 0 while committing state change");
+    }
+    g_assert (length <= 1);
   }
 
   /* see if we need to block now. We cannot block on events, only

gst/gstpad.c

@@ -198,8 +198,8 @@ gst_pad_class_init (GstPadClass * klass)
    * @pad: the pad that emitted the signal
    * @mini_obj: new data
    *
-   * Signals that new data is available on the pad. This signal is used 
-   * internally for implementing pad probes. 
+   * Signals that new data is available on the pad. This signal is used
+   * internally for implementing pad probes.
    * See gst_pad_add_*_probe functions.
    *
    * Returns: %TRUE to keep the data, %FALSE to drop it
@@ -3009,7 +3009,7 @@ flushing:
 dropping:
   {
     gst_buffer_unref (buffer);
-    GST_DEBUG ("Dropping buffer due to FALSE probe return");
+    GST_DEBUG_OBJECT (pad, "Dropping buffer due to FALSE probe return");
     GST_STREAM_UNLOCK (pad);
     return GST_FLOW_OK;
   }

gst/gstpluginfeature.c

@@ -80,11 +80,11 @@ gst_plugin_feature_finalize (GObject * object)
  * unaffected; use the return value instead.
  *
  * Normally this function is used like this:
- *  
+ *
  * <programlisting>
  * GstPluginFeature *loaded_feature;
  * loaded_feature = gst_plugin_feature_load (feature);
- *  
+ *
  * // presumably, we're no longer interested in the potentially-unloaded feature
  * gst_object_unref (feature);
  * feature = loaded_feature;

gst/gstutils.c

@@ -2446,7 +2446,7 @@ gst_atomic_int_set (gint * atomic_int, gint value)
  * to drop it. Dropping data is rarely useful, but occasionally comes in handy
  * with events.
  *
- * Although probes are implemeted internally by connecting @handler to the
+ * Although probes are implemented internally by connecting @handler to the
  * have-data signal on the pad, if you want to remove a probe it is insufficient
  * to only call g_signal_handler_disconnect on the returned handler id. To
  * remove a probe, use the appropriate function, such as

libs/gst/base/gstbasesink.c

@@ -650,9 +650,16 @@ gst_base_sink_handle_object (GstBaseSink * basesink, GstPad * pad,
     if (!basesink->need_preroll)
       goto no_preroll;
 
+
     length = basesink->preroll_queued;
 
-    g_assert (length == 1);
+    /* FIXME: a pad probe could have made us lose the buffer, according
+     * to one of the python tests */
+    if (length == 0) {
+      GST_ERROR_OBJECT (basesink,
+          "preroll_queued dropped from 1 to 0 while committing state change");
+    }
+    g_assert (length <= 1);
   }
 
   /* see if we need to block now. We cannot block on events, only