gst/gsttagsetter.c: Docs additions and fixes (see #339918).

Original commit message from CVS:
* gst/gsttagsetter.c:
Docs additions and fixes (see #339918).

diff --git a/ChangeLog b/ChangeLog
index 1703b72..fb9c0bf 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2006-05-18  Tim-Philipp Müller  <tim at centricular dot net>
+
+       * gst/gsttagsetter.c:
+         Docs additions and fixes (see #339918).
+
 2006-05-18  Jan Schmidt  <thaytan@mad.scientist.com>
 
        * plugins/elements/gstcapsfilter.c: (gst_capsfilter_prepare_buf):

diff --git a/common b/common
index 8eb9ea4..a5b6630 160000 (submodule)
--- a/common
+++ b/common
@@ -1 +1 @@
-Subproject commit 8eb9ea46137c34191bdbeca946ca4419ba573b51
+Subproject commit a5b66304e7abe1440a0f8b0ed232ffbc56e8f3de

diff --git a/gst/gsttagsetter.c b/gst/gsttagsetter.c
index 1ec0a3e..10301a4 100644 (file)
--- a/gst/gsttagsetter.c
+++ b/gst/gsttagsetter.c
@@ -24,9 +24,52 @@
  * @short_description: Element interface that allows setting and retrieval
  *                     of media metadata
  *
- * Element interface that allows setting and retrieval of media metadata.
- *
- * Last reviewed on 2005-11-23 (0.9.5)
+ * <refsect2>
+ * <para>
+ * Element interface that allows setting of media metadata.
+ * </para>
+ * <para>
+ * Elements that support changing a stream's metadata will implement this
+ * interface. Examples of such elements are 'vorbisenc', 'theoraenc' and
+ * 'id3v2mux'.
+ * </para>
+ * <para>
+ * If you just want to retrieve metadata in your application then all you
+ * need to do is watch for tag messages on your pipeline's bus. This
+ * interface is only for setting metadata, not for extracting it.
+ * </para>
+ * <para>
+ * Elements implementing the #GstTagSetter interface often have to merge
+ * any tags received from upstream and the tags set by the application via
+ * the interface. This can be done like this:
+ * </para>
+ * <para>
+ * <programlisting>
+ * GstTagMergeMode merge_mode;
+ * const GstTagList *application_tags;
+ * const GstTagList *event_tags;
+ * GstTagSetter *tagsetter;
+ * GstTagList *result;
+ *  
+ * tagsetter = GST_TAG_SETTER (element);
+ *  
+ * merge_mode = gst_tag_setter_get_tag_merge_mode (tagsetter);
+ * tagsetter_tags = gst_tag_setter_get_tag_list (tagsetter);
+ * event_tags = (const GstTagList *) element->event_tags;
+ *  
+ * GST_LOG_OBJECT (tagsetter, "merging tags, merge mode = %d", merge_mode);
+ * GST_LOG_OBJECT (tagsetter, "event tags: %" GST_PTR_FORMAT, event_tags);
+ * GST_LOG_OBJECT (tagsetter, "set   tags: %" GST_PTR_FORMAT, application_tags);
+ *  
+ * result = gst_tag_list_merge (application_tags, event_tags, merge_mode);
+ *  
+ * GST_LOG_OBJECT (tagsetter, "final tags: %" GST_PTR_FORMAT, result);
+ * </programlisting>
+ * </para>
+ * <para>
+ * Last reviewed on 2006-05-18 (0.10.6)
+ * </para>
+ * </refsect2>
  */
 
 #ifdef HAVE_CONFIG_H
@@ -258,7 +301,7 @@ gst_tag_setter_get_tag_list (GstTagSetter * setter)
  *
  * Sets the given merge mode that is used for adding tags from events to tags
  * specified by this interface. The default is #GST_TAG_MERGE_KEEP, which keeps
- * the tags by this interface and discards tags from events.
+ * the tags set with this interface and discards tags from events.
  */
 void
 gst_tag_setter_set_tag_merge_mode (GstTagSetter * setter, GstTagMergeMode mode)