gst/gststructure.c: Fix typo in docs and re-wrap docs blurb to not exceed 80 chars...

Original commit message from CVS:
* gst/gststructure.c:
Fix typo in docs and re-wrap docs blurb to not exceed 80 chars/line.
* gst/gstvalue.h:
Expand on the difference between arrays and lists as we use them.

diff --git a/ChangeLog b/ChangeLog
index 21da607..1c1347d 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2006-08-14  Tim-Philipp Müller  <tim at centricular dot net>
+
+       * gst/gststructure.c:
+         Fix typo in docs and re-wrap docs blurb to not exceed 80 chars/line.
+
+       * gst/gstvalue.h:
+         Expand on the difference between arrays and lists as we use them.
+         
 2006-08-14  Wim Taymans  <wim@fluendo.com>
 
        * libs/gst/base/gstbasesrc.c: (gst_base_src_change_state):

diff --git a/gst/gststructure.c b/gst/gststructure.c
index cb22f46..b86b7b0 100644 (file)
--- a/gst/gststructure.c
+++ b/gst/gststructure.c
@@ -24,27 +24,29 @@
  * @short_description: Generic structure containing fields of names and values
  * @see_also: #GstCaps, #GstMessage, #GstEvent, #GstQuery
  *
- * A #GstStructure is a collection of key/value pairs. The keys are expressed as
- * GQuarks and the values can be of any GType.
+ * A #GstStructure is a collection of key/value pairs. The keys are expressed
+ * as GQuarks and the values can be of any GType.
  *
  * In addition to the key/value pairs, a #GstStructure also has a name.
  * 
- * #GstStructure is used by various GStreamer subsystems to store information in
- * a flexible an extensible way. A #GstStructure does not have a refcount because it
- * usually is part of a higher level object such as #GstCaps. It provides a means to 
- * enforce mutability using the refcount of the parent with the 
- * gst_structure_set_parent_refcount() method.
- *
- * A #GstStructure can be created with gst_structure_empty_new() or gst_structure_new(),
- * which both take a name and an optional set of key/value pairs along with the types
- * of the values.
+ * #GstStructure is used by various GStreamer subsystems to store information
+ * in a flexible and extensible way. A #GstStructure does not have a refcount
+ * because it usually is part of a higher level object such as #GstCaps. It
+ * provides a means to enforce mutability using the refcount of the parent
+ * with the gst_structure_set_parent_refcount() method.
+ *
+ * A #GstStructure can be created with gst_structure_empty_new() or
+ * gst_structure_new(), which both take a name and an optional set of
+ * key/value pairs along with the types of the values.
  * 
- * Field values can be changed with gst_structure_set_value() or gst_structure_set().
+ * Field values can be changed with gst_structure_set_value() or
+ * gst_structure_set().
  *
- * Field values can be retrieved with gst_structure_get_value() or the more convenient
- * gst_structure_get_*() functions.
+ * Field values can be retrieved with gst_structure_get_value() or the more
+ * convenient gst_structure_get_*() functions.
  *
- * Fields can be removed with gst_structure_remove_field() or gst_structure_remove_fields().
+ * Fields can be removed with gst_structure_remove_field() or
+ * gst_structure_remove_fields().
  *
  * Last reviewed on 2005-11-09 (0.9.4)
  */
@@ -975,8 +977,8 @@ gst_structure_has_field_typed (const GstStructure * structure,
  * and has the correct type.
  *
  * Returns: TRUE if the value could be set correctly. If there was no field
- * with @fieldname or the existing field did not contain a boolean, this function
- * returns FALSE.
+ * with @fieldname or the existing field did not contain a boolean, this
+ * function returns FALSE.
  */
 gboolean
 gst_structure_get_boolean (const GstStructure * structure,

diff --git a/gst/gstvalue.h b/gst/gstvalue.h
index 4a19f0d..f6b59d9 100644 (file)
--- a/gst/gstvalue.h
+++ b/gst/gstvalue.h
@@ -203,7 +203,11 @@ G_BEGIN_DECLS
 /**
  * GST_TYPE_LIST:
  *
- * a #GValue type that represents an unordered list of #GValue values
+ * a #GValue type that represents an unordered list of #GValue values. This
+ * is used for example to express a list of possible values for a field in
+ * a caps structure, like a list of possible sample rates, of which only one
+ * will be chosen in the end. This means that all values in the list are
+ * meaningful on their own.
  *
  * Returns: the #GType of GstValueList (which is not explicitly typed)
  */
@@ -212,7 +216,12 @@ G_BEGIN_DECLS
 /**
  * GST_TYPE_ARRAY:
  *
- * a #GValue type that represents an ordered list of #GValue values
+ * a #GValue type that represents an ordered list of #GValue values. This is
+ * used to express a set of values that is meaningful only in their specific
+ * combination and order of values. Each value on its own is not particularly
+ * meaningful, only the ordered array in its entirety is meaningful. This is
+ * used for example to express channel layouts for multichannel audio where
+ * each channel needs to be mapped to a position in the room.
  *
  * Returns: the #GType of GstArrayList (which is not explicitly typed)
  */