From c1b135b4a39c5fccbc53324f6644573e388d4fd0 Mon Sep 17 00:00:00 2001
From: Wim Taymans <wim.taymans@gmail.com>
Date: Tue, 14 Feb 2006 13:07:10 +0000
Subject: [PATCH] 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                   |  9 +++++++++
 gst/gstbuffer.c             |  6 ++++++
 gst/gstquery.c              | 23 +++++++++++++++++++++++
 libs/gst/base/gstbasesink.c |  4 +++-
 4 files changed, 41 insertions(+), 1 deletion(-)

diff --git a/ChangeLog b/ChangeLog
index 96c0a74293..4bb9e82192 100644
--- a/ChangeLog
+++ b/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:
diff --git a/gst/gstbuffer.c b/gst/gstbuffer.c
index 6248f1c6c8..8309199e73 100644
--- a/gst/gstbuffer.c
+++ b/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)
diff --git a/gst/gstquery.c b/gst/gstquery.c
index d698138269..7276054609 100644
--- a/gst/gstquery.c
+++ b/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>
 
diff --git a/libs/gst/base/gstbasesink.c b/libs/gst/base/gstbasesink.c
index 4c2f0b7fb9..c0202a5a5b 100644
--- a/libs/gst/base/gstbasesink.c
+++ b/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;