Add lot of documentation.

Original commit message from CVS:
Add lot of documentation.

1 files changed, 247 insertions, 85 deletions

diff --git a/ext/metadata/metadataiptc.c b/ext/metadata/metadataiptc.c
index 0b040ede..31388372 100644
--- a/ext/metadata/metadataiptc.c
+++ b/ext/metadata/metadataiptc.c
@@ -41,23 +41,51 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/*
+ * SECTION: metadataiptc
+ * @short_description: This module provides functions to extract tags from
+ * IPTC metadata chunks and create IPTC chunks from metadata tags.
+ * @see_also: #metadatatags.[c/h]
+ *
+ * If libiptcdata isn't available at compilation time, only the whole chunk
+ * (#METADATA_TAG_MAP_WHOLECHUNK) tags is created. It means that individual
+ * tags aren't mapped.
+ *
+ * Last reviewed on 2008-01-24 (0.10.15)
+ */
+
+/*
+ * includes
+ */
+
 #include "metadataiptc.h"
 #include "metadataparseutil.h"
 #include "metadatatags.h"
 
+/*
+ * defines
+ */
+
 GST_DEBUG_CATEGORY (gst_metadata_iptc_debug);
 #define GST_CAT_DEFAULT gst_metadata_iptc_debug
 
+/*
+ * Implementation when libiptcdata isn't available at compilation time
+ */
+
 #ifndef HAVE_IPTC
 
+/*
+ * extern functions implementations
+ */
+
 void
 metadataparse_iptc_tag_list_add (GstTagList * taglist, GstTagMergeMode mode,
     GstAdapter * adapter, MetadataTagMapping mapping)
 {
 
   if (mapping & METADATA_TAG_MAP_WHOLECHUNK) {
-    GST_LOG
-        ("IPTC not defined, here I should send just one tag as whole chunk");
+    GST_LOG ("IPTC not defined, sending just one tag as whole chunk");
     metadataparse_util_tag_list_add_chunk (taglist, mode, GST_TAG_IPTC,
         adapter);
   }
@@ -74,11 +102,23 @@ metadatamux_iptc_create_chunk_from_tag_list (guint8 ** buf, guint32 * size,
 
 #else /* ifndef HAVE_IPTC */
 
+/*
+ * Implementation when libiptcdata is available at compilation time
+ */
+
+/*
+ * includes
+ */
+
 #include <iptc-data.h>
 #include <iptc-tag.h>
 #include <string.h>
 #include <gst/gsttaglist.h>
 
+/*
+ * enum and types
+ */
+
 typedef struct _tag_MEUserData
 {
   GstTagList *taglist;
@@ -92,56 +132,62 @@ typedef struct _tag_MapIntStr
   const gchar *str;
 } MapIntStr;
 
-static void
-iptc_data_foreach_dataset_func (IptcDataSet * dataset, void *user_data);
+/*
+ * defines and static global vars
+ */
 
 /* *INDENT-OFF* */
 static MapIntStr mappedTags[] = {
-  {IPTC_RECORD_APP_2, IPTC_TAG_OBJECT_NAME,      /*ASCII*/ GST_TAG_TITLE       /*STRING*/},
-  {IPTC_RECORD_APP_2, IPTC_TAG_BYLINE,           /*ASCII*/ GST_TAG_COMPOSER    /*STRING*/},
-  {IPTC_RECORD_APP_2, IPTC_TAG_CAPTION,          /*ASCII*/ GST_TAG_DESCRIPTION /*STRING*/},
-  {IPTC_RECORD_APP_2, IPTC_TAG_COPYRIGHT_NOTICE, /*ASCII*/ GST_TAG_COPYRIGHT   /*STRING*/},
+  {IPTC_RECORD_APP_2, IPTC_TAG_OBJECT_NAME,      /*ASCII*/
+   GST_TAG_TITLE      /*STRING*/},
+  {IPTC_RECORD_APP_2, IPTC_TAG_BYLINE,           /*ASCII*/
+   GST_TAG_COMPOSER    /*STRING*/},
+  {IPTC_RECORD_APP_2, IPTC_TAG_CAPTION,          /*ASCII*/
+   GST_TAG_DESCRIPTION /*STRING*/},
+  {IPTC_RECORD_APP_2, IPTC_TAG_COPYRIGHT_NOTICE, /*ASCII*/
+   GST_TAG_COPYRIGHT   /*STRING*/},
   {0, 0, NULL}
 };
 /* *INDENT-ON* */
 
-static const gchar *
-metadataparse_iptc_get_tag_from_iptc (IptcTag iptc, GType * type,
-    IptcRecord * record)
-{
-  int i = 0;
-
-  while (mappedTags[i].iptc) {
-    if (iptc == mappedTags[i].iptc) {
-      *type = gst_tag_get_type (mappedTags[i].str);
-      *record = mappedTags[i].record;
-      break;
-    }
-    ++i;
-  }
+/*
+ * static helper functions declaration
+ */
 
-  return mappedTags[i].str;
+static const gchar *metadataparse_iptc_get_tag_from_iptc (IptcTag iptc,
+    GType * type, IptcRecord * record);
 
-}
 
 static IptcTag
-metadataparse_iptc_get_iptc_from_tag (const gchar * tag, GType * type,
-    IptcRecord * record)
-{
-  int i = 0;
+metadatamux_iptc_get_iptc_from_tag (const gchar * tag, GType * type,
+    IptcRecord * record);
 
-  while (mappedTags[i].iptc) {
-    if (0 == strcmp (mappedTags[i].str, tag)) {
-      *type = gst_tag_get_type (tag);
-      *record = mappedTags[i].record;
-      break;
-    }
-    ++i;
-  }
+static void
+metadataparse_iptc_data_foreach_dataset_func (IptcDataSet * dataset,
+    void *user_data);
 
-  return mappedTags[i].iptc;
+static void
+metadatamux_iptc_for_each_tag_in_list (const GstTagList * list,
+    const gchar * tag, gpointer user_data);
 
-}
+/*
+ * extern functions implementations
+ */
+
+/*
+ * metadataparse_iptc_tag_list_add:
+ * @taglist: tag list in which extracted tags will be added
+ * @mode: tag list merge mode
+ * @adapter: contains the IPTC metadata chunk
+ * @mapping: if is to extract individual tags and/or the whole chunk.
+ * 
+ * This function gets a IPTC chunk (@adapter) and extract tags form it 
+ * and then add to @taglist.
+ * Note: The IPTC chunk (@adapetr) must NOT be wrapped by any bytes specific
+ * to any file format
+ *
+ * Returns: nothing
+ */
 
 void
 metadataparse_iptc_tag_list_add (GstTagList * taglist, GstTagMergeMode mode,
@@ -171,8 +217,63 @@ metadataparse_iptc_tag_list_add (GstTagList * taglist, GstTagMergeMode mode,
     goto done;
   }
 
-  iptc_data_foreach_dataset (iptc, iptc_data_foreach_dataset_func,
-      (void *) &user_data);
+  iptc_data_foreach_dataset (iptc,
+      metadataparse_iptc_data_foreach_dataset_func, (void *) &user_data);
+
+done:
+
+  if (iptc)
+    iptc_data_unref (iptc);
+
+  return;
+
+}
+
+/*
+ * metadatamux_iptc_create_chunk_from_tag_list:
+ * @buf: buffer that will have the created IPTC chunk
+ * @size: size of the buffer that will be created
+ * @taglist: list of tags to be added to IPTC chunk
+ *
+ * Get tags from @taglist, create a IPTC chunk based on it and save to @buf.
+ * Note: The IPTC chunk is NOT wrapped by any bytes specific to any file format
+ *
+ * Returns: nothing
+ */
+
+void
+metadatamux_iptc_create_chunk_from_tag_list (guint8 ** buf, guint32 * size,
+    const GstTagList * taglist)
+{
+  IptcData *iptc = NULL;
+  GstBuffer *iptc_chunk = NULL;
+  const GValue *val = NULL;
+
+  if (!(buf && size))
+    goto done;
+  if (*buf) {
+    g_free (*buf);
+    *buf = NULL;
+  }
+  *size = 0;
+
+  val = gst_tag_list_get_value_index (taglist, GST_TAG_IPTC, 0);
+  if (val) {
+    iptc_chunk = gst_value_get_buffer (val);
+    if (iptc_chunk) {
+      iptc = iptc_data_new_from_data (GST_BUFFER_DATA (iptc_chunk),
+          GST_BUFFER_SIZE (iptc_chunk));
+    }
+  }
+
+  if (!iptc) {
+    iptc = iptc_data_new ();
+  }
+
+  gst_tag_list_foreach (taglist, metadatamux_iptc_for_each_tag_in_list, iptc);
+
+  iptc_data_save (iptc, buf, size);
+
 
 done:
 
@@ -180,11 +281,100 @@ done:
     iptc_data_unref (iptc);
 
   return;
+}
+
+/*
+ * static helper functions implementation
+ */
+
+/*
+ * metadataparse_iptc_get_tag_from_iptc:
+ * @iptc: IPTC tag to look for
+ * @type: the type of the GStreamer tag mapped to @iptc
+ * @record: the place into IPTC chunk @iptc belongs to.
+ *
+ * This returns the GStreamer tag mapped to an IPTC tag.
+ *
+ * Returns:
+ * <itemizedlist>
+ * <listitem><para>The GStreamer tag mapped to the @iptc
+ * </para></listitem>
+ * <listitem><para>%NULL if there is no mapped GST tag for @iptc
+ * </para></listitem>
+ * </itemizedlist>
+ */
+
+static const gchar *
+metadataparse_iptc_get_tag_from_iptc (IptcTag iptc, GType * type,
+    IptcRecord * record)
+{
+  int i = 0;
+
+  while (mappedTags[i].iptc) {
+    if (iptc == mappedTags[i].iptc) {
+      *type = gst_tag_get_type (mappedTags[i].str);
+      *record = mappedTags[i].record;
+      break;
+    }
+    ++i;
+  }
+
+  return mappedTags[i].str;
 
 }
 
+/*
+ * metadatamux_iptc_get_iptc_from_tag:
+ * @tag: GST tag to look for
+ * @type: the type of the GStreamer @tag
+ * @record: the place into IPTC chunk @iptc belongs to.
+ *
+ * This returns thet IPTC tag mapped to an GStreamer @tag.
+ *
+ * Returns:
+ * <itemizedlist>
+ * <listitem><para>The IPTC tag mapped to the GST @tag
+ * </para></listitem>
+ * <listitem><para>0 if there is no mapped IPTC tag for GST @tag
+ * </para></listitem>
+ * </itemizedlist>
+ */
+
+static IptcTag
+metadatamux_iptc_get_iptc_from_tag (const gchar * tag, GType * type,
+    IptcRecord * record)
+{
+  int i = 0;
+
+  while (mappedTags[i].iptc) {
+    if (0 == strcmp (mappedTags[i].str, tag)) {
+      *type = gst_tag_get_type (tag);
+      *record = mappedTags[i].record;
+      break;
+    }
+    ++i;
+  }
+
+  return mappedTags[i].iptc;
+
+}
+
+/*
+ * metadataparse_iptc_data_foreach_dataset_func:
+ * @dataset: IPTC structure from libiptcdata having IPTC tag
+ * @user_data: pointer to #MEUserData
+ *
+ * This function designed to be called for each IPTC tag in a IPTC chunk. This
+ * function gets the IPTC tag from @dataset and then add to the tag list
+ * in @user_data by using a merge mode also specified in @user_data
+ * @see_also: #metadataparse_iptc_tag_list_add
+ *
+ * Returns: nothing
+ */
+
 static void
-iptc_data_foreach_dataset_func (IptcDataSet * dataset, void *user_data)
+metadataparse_iptc_data_foreach_dataset_func (IptcDataSet * dataset,
+    void *user_data)
 {
 
   char buf[1024];
@@ -213,10 +403,23 @@ done:
 
 }
 
+/*
+ * metadatamux_iptc_for_each_tag_in_list:
+ * @list: GStreamer tag list from which @tag belongs to
+ * @tag: GStreamer tag to be added to the IPTC chunk
+ * @user_data: pointer to #IptcData in which the tag will be added
+ *
+ * This function designed to be called for each tag in GST tag list. This
+ * function adds get the tag value from tag @list and then add it to the IPTC
+ * chunk by using #IptcData and related functions from libiptcdata
+ * @see_also: #metadatamux_iptc_create_chunk_from_tag_list
+ *
+ * Returns: nothing
+ */
 
 static void
-metadataiptc_for_each_tag_in_list (const GstTagList * list, const gchar * tag,
-    gpointer user_data)
+metadatamux_iptc_for_each_tag_in_list (const GstTagList * list,
+    const gchar * tag, gpointer user_data)
 {
   IptcData *iptc = (IptcData *) user_data;
   IptcTag iptc_tag;
@@ -226,7 +429,7 @@ metadataiptc_for_each_tag_in_list (const GstTagList * list, const gchar * tag,
   gboolean new_dataset = FALSE;
   gchar *tag_value = NULL;
 
-  iptc_tag = metadataparse_iptc_get_iptc_from_tag (tag, &type, &record);
+  iptc_tag = metadatamux_iptc_get_iptc_from_tag (tag, &type, &record);
 
   if (!iptc_tag)
     goto done;
@@ -257,46 +460,5 @@ done:
     iptc_dataset_unref (dataset);
 }
 
-void
-metadatamux_iptc_create_chunk_from_tag_list (guint8 ** buf, guint32 * size,
-    const GstTagList * taglist)
-{
-  IptcData *iptc = NULL;
-  GstBuffer *iptc_chunk = NULL;
-  const GValue *val = NULL;
-
-  if (!(buf && size))
-    goto done;
-  if (*buf) {
-    g_free (*buf);
-    *buf = NULL;
-  }
-  *size = 0;
-
-  val = gst_tag_list_get_value_index (taglist, GST_TAG_IPTC, 0);
-  if (val) {
-    iptc_chunk = gst_value_get_buffer (val);
-    if (iptc_chunk) {
-      iptc = iptc_data_new_from_data (GST_BUFFER_DATA (iptc_chunk),
-          GST_BUFFER_SIZE (iptc_chunk));
-    }
-  }
-
-  if (!iptc) {
-    iptc = iptc_data_new ();
-  }
-
-  gst_tag_list_foreach (taglist, metadataiptc_for_each_tag_in_list, iptc);
-
-  iptc_data_save (iptc, buf, size);
-
-
-done:
-
-  if (iptc)
-    iptc_data_unref (iptc);
-
-  return;
-}
 
 #endif /* else (ifndef HAVE_IPTC) */