gst/: Add more docs regarding tag merge-modes and when to send tags. Fix 'since'...

Original commit message from CVS:
* gst/gsttaglist.h:
* gst/gsttagsetter.c:
Add more docs regarding tag merge-modes and when to send tags. Fix 'since'
statement for new tag.

diff --git a/ChangeLog b/ChangeLog
index 07a50f4..6368ed9 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2007-01-18  Stefan Kost  <ensonic@users.sf.net>
+
+       * gst/gsttaglist.h:
+       * gst/gsttagsetter.c:
+       Add more docs regarding tag merge-modes and when to send tags. Fix 'since'
+       statement for new tag.
+
 2007-01-17  Edward Hervey  <edward@fluendo.com>
 
        * plugins/elements/gstmultiqueue.c: (gst_single_queue_new):

diff --git a/gst/gsttaglist.h b/gst/gsttaglist.h
index 7e90cc9..ce48791 100644 (file)
--- a/gst/gsttaglist.h
+++ b/gst/gsttaglist.h
@@ -31,7 +31,7 @@ G_BEGIN_DECLS
 /**
  * GstTagMergeMode:
  * @GST_TAG_MERGE_UNDEFINED: undefined merge mode
- * @GST_TAG_MERGE_REPLACE_ALL: replace all tags
+ * @GST_TAG_MERGE_REPLACE_ALL: replace all tags (clear list and append)
  * @GST_TAG_MERGE_REPLACE: replace tags
  * @GST_TAG_MERGE_APPEND: append tags
  * @GST_TAG_MERGE_PREPEND: prepend tags
@@ -39,7 +39,72 @@ G_BEGIN_DECLS
  * @GST_TAG_MERGE_KEEP_ALL: keep all existing tags
  * @GST_TAG_MERGE_COUNT: the number of merge modes
  *
- * The different tag merging modes.
+ * The different tag merging modes are basically replace, overwrite and append,
+ * but they can be seen from two directions.
+ * Given two taglists: A - the one that are supplied to
+ * gst_tag_setter_merge_tags() or gst_tag_setter_add_tags() and B - the tags
+ * already in the element, how are the tags merged? In the table below this is
+ * shown for the cases that a tag exists in the list (A) or does not exists (!A)
+ * and combination thereof.
+ *
+ * <table frame="all" colsep="1" rowsep="1">
+ *   <title>merge mode</title>
+ *   <tgroup cols='5' align='left'>
+ *     <thead>
+ *       <row>
+ *         <entry>merge mode</entry>
+ *         <entry>A + B</entry>
+ *         <entry>A + !B</entry>
+ *         <entry>!A + B</entry>
+ *         <entry>!A + !B</entry>
+ *       </row>
+ *     </thead>
+ *     <tbody>
+ *       <row>
+ *         <entry>REPLACE_ALL</entry>
+ *         <entry>B</entry>
+ *         <entry>-</entry>
+ *         <entry>B</entry>
+ *         <entry>-</entry>
+ *       </row>
+ *       <row>
+ *         <entry>REPLACE</entry>
+ *         <entry>B</entry>
+ *         <entry>A</entry>
+ *         <entry>B</entry>
+ *         <entry>-</entry>
+ *       </row>
+ *       <row>
+ *         <entry>APPEND</entry>
+ *         <entry>A, B</entry>
+ *         <entry>A</entry>
+ *         <entry>B</entry>
+ *         <entry>-</entry>
+ *       </row>
+ *       <row>
+ *         <entry>PREPEND</entry>
+ *         <entry>B, A</entry>
+ *         <entry>A</entry>
+ *         <entry>B</entry>
+ *         <entry>-</entry>
+ *       </row>
+ *       <row>
+ *         <entry>KEEP</entry>
+ *         <entry>A</entry>
+ *         <entry>A</entry>
+ *         <entry>B</entry>
+ *         <entry>-</entry>
+ *       </row>
+ *       <row>
+ *         <entry>KEEP_ALL</entry>
+ *         <entry>A</entry>
+ *         <entry>A</entry>
+ *         <entry>-</entry>
+ *         <entry>-</entry>
+ *       </row>
+ *     </tbody>
+ *   </tgroup>
+ * </table>
  */
 typedef enum {
   GST_TAG_MERGE_UNDEFINED,
@@ -523,7 +588,7 @@ gboolean     gst_tag_list_get_date_index    (const GstTagList * list,
  *
  * number of beats per minute in audio
  *
- * Since: 0.10.11
+ * Since: 0.10.12
  */
 #define GST_TAG_BEATS_PER_MINUTE       "beats-per-minute"
 

diff --git a/gst/gsttagsetter.c b/gst/gsttagsetter.c
index 453c9e8..31f65a6 100644 (file)
--- a/gst/gsttagsetter.c
+++ b/gst/gsttagsetter.c
@@ -36,7 +36,10 @@
  * <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.
+ * interface is only for setting metadata, not for extracting it. To set tags
+ * from the application, find tagsetter elements and set tags using e.g.
+ * gst_tag_setter_merge_tags() or gst_tag_setter_add_tags(). The application
+ * should do that before the element goes to %GST_STATE_PAUSED.
  * </para>
  * <para>
  * Elements implementing the #GstTagSetter interface often have to merge