Docs fixes.

Original commit message from CVS:
* gst/gstbuffer.c:
* gst/gstquery.c: (gst_query_list_add_format),
(gst_query_set_formatsv), (gst_query_parse_formats_length),
(gst_query_parse_formats_nth):
* libs/gst/base/gstbasesink.c: (gst_base_sink_get_sync_times):
Docs fixes.

ChangeLog

@@ -1,3 +1,12 @@
+2006-02-14  Wim Taymans  <wim@fluendo.com>
+
+	* gst/gstbuffer.c:
+	* gst/gstquery.c: (gst_query_list_add_format),
+	(gst_query_set_formatsv), (gst_query_parse_formats_length),
+	(gst_query_parse_formats_nth):
+	* libs/gst/base/gstbasesink.c: (gst_base_sink_get_sync_times):
+	Docs fixes.
+
 2006-02-14  Wim Taymans  <wim@fluendo.com>
 
 	* docs/gst/gstreamer-sections.txt:

gst/gstbuffer.c

@@ -345,6 +345,8 @@ gst_buffer_set_caps (GstBuffer * buffer, GstCaps * caps)
  * Similar to gst_buffer_is_writable, but this only ensures that the
  * refcount of the buffer is 1, indicating that the caller is the sole
  * owner and can change the buffer metadata, such as caps and timestamps.
+ *
+ * Returns: TRUE if the metadata is writable.
  */
 gboolean
 gst_buffer_is_metadata_writable (GstBuffer * buf)
@@ -360,6 +362,10 @@ gst_buffer_is_metadata_writable (GstBuffer * buf)
  * data array is writable. Instead, this just ensures that the returned buffer
  * is solely owned by the caller, by creating a subbuffer of the original
  * buffer if necessary.
+ * 
+ * After calling this function, @buf should not be referenced anymore.
+ *
+ * Returns: A new #GstBuffer with writable metadata.
  */
 GstBuffer *
 gst_buffer_make_metadata_writable (GstBuffer * buf)

gst/gstquery.c

@@ -34,6 +34,29 @@
  * Queries can be created using the gst_query_new_xxx() functions.  
  * Query values can be set using gst_query_set_xxx(), and parsed using 
  * gst_query_parse_xxx() helpers.
+ *
+ * The following example shows how to query the duration of a pipeline:
+ * 
+ * <example>
+ *  <title>Query duration on a pipeline</title>
+ *  <programlisting>
+ *  GstQuery *query;
+ *  gboolean res;
+ *  query = gst_query_new_duration (GST_FORMAT_TIME);
+ *  res = gst_element_query (pipeline, query);
+ *  if (res) {
+ *    gint64 duration;
+ *    gst_query_parse_duration (query, NULL, &amp;duration);
+ *    g_print ("duration = %"GST_TIME_FORMAT, GST_TIME_ARGS (duration));
+ *  }
+ *  else {
+ *    g_print ("duration query failed...");
+ *  }
+ *  gst_query_unref (query);
+ *  </programlisting>
+ * </example>
+ *
+ * Last reviewed on 2006-02-14 (0.10.4)
  */
 #include <string.h>
 

libs/gst/base/gstbasesink.c

@@ -598,7 +598,9 @@ gst_base_sink_get_sync_times (GstBaseSink * basesink, GstMiniObject * obj,
         return TRUE;
         /* other events do not need syncing */
         /* FIXME, maybe NEWSEGMENT might need synchronisation
-         * since the POSITION query depends on accumulated times 
+         * since the POSITION query depends on accumulated times and
+         * we cannot accumulate the current segment before the previous
+         * one completed.
          */
       default:
         return FALSE;