gst/gstbin.h: Document another field.

Original commit message from CVS:
* gst/gstbin.h:
Document another field.

* gst/gststructure.c:
* gst/gststructure.h:
Document.

diff --git a/ChangeLog b/ChangeLog
index 0c3bbc6ec661c8b00de1810c159ae0fe13ab22bc..d214346b18e4375cf6f45a1a47658c7dc57404ab 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,12 @@
+2005-11-09  Wim Taymans  <wim@fluendo.com>
+
+       * gst/gstbin.h:
+       Document another field.
+
+       * gst/gststructure.c:
+       * gst/gststructure.h:
+       Document.
+
 2005-11-09  Wim Taymans  <wim@fluendo.com>
 
        * gst/gstbin.h:

diff --git a/gst/gstbin.h b/gst/gstbin.h
index 8fc46573cca16839880d5cdd54f27569da57a9e2..384a7fdd98b1ee57c2332efaf72bb176f97f396c 100644 (file)
--- a/gst/gstbin.h
+++ b/gst/gstbin.h
@@ -117,6 +117,7 @@ struct _GstBin {
 
 /**
  * GstBinClass:
+ * @parent_class: bin parent class
  * @add_element: method to add an element to a bin
  * @remove_element: method to remove an element from a bin
  *

diff --git a/gst/gststructure.c b/gst/gststructure.c
index cce7c8037586f09eb8f43c80c33cb824a5a779b4..beaec089ec48b95d37c6da912569311d37227107 100644 (file)
--- a/gst/gststructure.c
+++ b/gst/gststructure.c
@@ -22,7 +22,31 @@
 /**
  * SECTION:gststructure
  * @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.
+ *
+ * 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.
+ * 
+ * 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.
+ *
+ * Fields can be removed with gst_structure_remove_field() or gst_structure_remove_fields().
+ *
+ * Last reviewed on 2005-11-09 (0.9.4)
  */
 
 #ifdef HAVE_CONFIG_H
@@ -99,7 +123,7 @@ gst_structure_id_empty_new_with_size (GQuark quark, guint prealloc)
  * gst_structure_id_empty_new:
  * @quark: name of new structure
  *
- * Creates a new, empty #GstStructure with the given name.
+ * Creates a new, empty #GstStructure with the given name as a GQuark.
  *
  * Returns: a new, empty #GstStructure
  */
@@ -190,7 +214,7 @@ gst_structure_new_valist (const gchar * name,
  *
  * Sets the parent_refcount field of #GstStructure. This field is used to
  * determine whether a structure is mutable or not. This function should only be
- * called by code implementing parent objects of GstStructure, as described in
+ * called by code implementing parent objects of #GstStructure, as described in
  * the MT Refcounting section of the design documents.
  */
 void
@@ -276,7 +300,7 @@ gst_structure_free (GstStructure * structure)
  * gst_structure_get_name:
  * @structure: a #GstStructure
  *
- * Accessor fuction.
+ * Get the name of @structure as a string.
  *
  * Returns: the name of the structure.
  */
@@ -314,7 +338,7 @@ gst_structure_has_name (const GstStructure * structure, const gchar * name)
  * gst_structure_get_name_id:
  * @structure: a #GstStructure
  *
- * Accessor fuction.
+ * Get the name of @structure as a GQuark.
  *
  * Returns: the quark representing the name of the structure.
  */
@@ -350,9 +374,9 @@ gst_structure_set_name (GstStructure * structure, const gchar * name)
  * @field: a #GQuark representing a field
  * @value: the new value of the field
  *
- * Sets the field with the given ID to the provided value.  If the field
+ * Sets the field with the given GQuark @field to @value.  If the field
  * does not exist, it is created.  If the field exists, the previous
- * value is freed.
+ * value is replaced and freed.
  */
 void
 gst_structure_id_set_value (GstStructure * structure,
@@ -376,9 +400,9 @@ gst_structure_id_set_value (GstStructure * structure,
  * @fieldname: the name of the field to set
  * @value: the new value of the field
  *
- * Sets the field with the given name to the provided value.  If the field
+ * Sets the field with the given name @field to @value.  If the field
  * does not exist, it is created.  If the field exists, the previous
- * value is freed.
+ * value is replaced and freed.
  */
 void
 gst_structure_set_value (GstStructure * structure,
@@ -401,7 +425,7 @@ gst_structure_set_value (GstStructure * structure,
  *
  * Parses the variable arguments and sets fields accordingly.
  * Variable arguments should be in the form field name, field type
- * (as a GType), value.  The last variable argument should be NULL.
+ * (as a GType), value(s).  The last variable argument should be NULL.
  */
 void
 gst_structure_set (GstStructure * structure, const gchar * field, ...)
@@ -522,7 +546,7 @@ gst_structure_get_field (const GstStructure * structure,
  * @structure: a #GstStructure
  * @fieldname: the name of the field to get
  *
- * Accessor function.
+ * Get the value of the field with name @fieldname.
  *
  * Returns: the #GValue corresponding to the field with the given name.
  */
@@ -547,7 +571,7 @@ gst_structure_get_value (const GstStructure * structure,
  * @structure: a #GstStructure
  * @field: the #GQuark of the field to get
  *
- * Accessor function.
+ * Get the value of the field with GQuark @field.
  *
  * Returns: the #GValue corresponding to the field with the given name
  *          identifier.
@@ -606,7 +630,7 @@ gst_structure_remove_field (GstStructure * structure, const gchar * fieldname)
  * @fieldname: the name of the field to remove
  * @...: NULL-terminated list of more fieldnames to remove
  *
- * Removes the field with the given names. If a field does not exist, the
+ * Removes the fields with the given names. If a field does not exist, the
  * argument is ignored.
  */
 void
@@ -632,8 +656,7 @@ gst_structure_remove_fields (GstStructure * structure,
  * @fieldname: the name of the field to remove
  * @varargs: NULL-terminated list of more fieldnames to remove
  *
- * Removes the field with the given names. If a field does not exist, the
- * argument is ignored.
+ * va_list form of #gst_structure_remove_fields.
  */
 void
 gst_structure_remove_fields_valist (GstStructure * structure,
@@ -707,7 +730,7 @@ gst_structure_get_field_type (const GstStructure * structure,
  * gst_structure_n_fields:
  * @structure: a #GstStructure
  *
- * Accessor function.
+ * Get the number of fields in the structure.
  *
  * Returns: the number of fields in the structure
  */
@@ -810,7 +833,7 @@ gst_structure_map_in_place (GstStructure * structure,
  * @structure: a #GstStructure
  * @fieldname: the name of a field
  *
- * Accessor function.
+ * Check if @structure contains a field named @fieldname.
  *
  * Returns: TRUE if the structure contains a field with the given name
  */
@@ -834,7 +857,7 @@ gst_structure_has_field (const GstStructure * structure,
  * @fieldname: the name of a field
  * @type: the type of a value
  *
- * Accessor function.
+ * Check if @structure contains a field named @fieldname and with GType @type.
  *
  * Returns: TRUE if the structure contains a field with the given name and type
  */
@@ -867,7 +890,9 @@ gst_structure_has_field_typed (const GstStructure * structure,
  * given field.  Caller is responsible for making sure the field exists
  * and has the correct type.
  *
- * Returns: TRUE if the value could be set correctly
+ * 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.
  */
 gboolean
 gst_structure_get_boolean (const GstStructure * structure,
@@ -900,7 +925,9 @@ gst_structure_get_boolean (const GstStructure * structure,
  * given field.  Caller is responsible for making sure the field exists
  * and has the correct type.
  *
- * Returns: TRUE if the value could be set correctly
+ * Returns: TRUE if the value could be set correctly. If there was no field
+ * with @fieldname or the existing field did not contain an int, this function
+ * returns FALSE.
  */
 gboolean
 gst_structure_get_int (const GstStructure * structure,
@@ -934,7 +961,9 @@ gst_structure_get_int (const GstStructure * structure,
  * given field.  Caller is responsible for making sure the field exists
  * and has the correct type.
  *
- * Returns: TRUE if the value could be set correctly
+ * Returns: TRUE if the value could be set correctly. If there was no field
+ * with @fieldname or the existing field did not contain a fourcc, this function
+ * returns FALSE.
  */
 gboolean
 gst_structure_get_fourcc (const GstStructure * structure,
@@ -968,7 +997,9 @@ gst_structure_get_fourcc (const GstStructure * structure,
  * given field.  Caller is responsible for making sure the field exists
  * and has the correct type.
  *
- * Returns: TRUE if the value could be set correctly
+ * Returns: TRUE if the value could be set correctly. If there was no field
+ * with @fieldname or the existing field did not contain a data, this function
+ * returns FALSE.
  */
 gboolean
 gst_structure_get_date (const GstStructure * structure, const gchar * fieldname,
@@ -1002,7 +1033,9 @@ gst_structure_get_date (const GstStructure * structure, const gchar * fieldname,
  * of the given field.  Caller is responsible for making sure the field exists
  * and has the correct type.
  *
- * Returns: TRUE if the value could be set correctly
+ * Returns: TRUE if the value could be set correctly. If there was no field
+ * with @fieldname or the existing field did not contain a #GstClockTime, this 
+ * function returns FALSE.
  */
 gboolean
 gst_structure_get_clock_time (const GstStructure * structure,
@@ -1036,7 +1069,9 @@ gst_structure_get_clock_time (const GstStructure * structure,
  * given field.  Caller is responsible for making sure the field exists
  * and has the correct type.
  *
- * Returns: TRUE if the value could be set correctly
+ * Returns: TRUE if the value could be set correctly. If there was no field
+ * with @fieldname or the existing field did not contain a double, this 
+ * function returns FALSE.
  */
 gboolean
 gst_structure_get_double (const GstStructure * structure,
@@ -1072,7 +1107,8 @@ gst_structure_get_double (const GstStructure * structure,
  * The string should not be modified, and remains valid until the next
  * call to a gst_structure_*() function with the given structure.
  *
- * Returns: a pointer to the string
+ * Returns: a pointer to the string or NULL when the field did not exist
+ * or did not contain a string.
  */
 const gchar *
 gst_structure_get_string (const GstStructure * structure,
@@ -1104,7 +1140,9 @@ gst_structure_get_string (const GstStructure * structure,
  * given field.  Caller is responsible for making sure the field exists,
  * has the correct type and that the enumtype is correct.
  *
- * Returns: TRUE if the value could be set correctly
+ * Returns: TRUE if the value could be set correctly. If there was no field
+ * with @fieldname or the existing field did not contain an enum of the given
+ * type, this function returns FALSE.
  */
 gboolean
 gst_structure_get_enum (const GstStructure * structure,
@@ -1260,9 +1298,10 @@ gst_structure_value_get_generic_type (GValue * val)
  * gst_structure_to_string:
  * @structure: a #GstStructure
  *
- * Converts @structure to a human-readable representation.
+ * Converts @structure to a human-readable string representation.
  *
- * Returns: a pointer to string allocated by g_malloc()
+ * Returns: a pointer to string allocated by g_malloc(). g_free after
+ * usage.
  */
 gchar *
 gst_structure_to_string (const GstStructure * structure)
@@ -1623,7 +1662,8 @@ gst_structure_parse_value (gchar * str,
  * If end is not NULL, a pointer to the place inside the given string
  * where parsing ended will be returned.
  *
- * Returns: a new #GstStructure
+ * Returns: a new #GstStructure or NULL when the string could not
+ * be parsed. Free after usage.
  */
 GstStructure *
 gst_structure_from_string (const gchar * string, gchar ** end)

diff --git a/gst/gststructure.h b/gst/gststructure.h
index 399acfb9e6747d39a3206e08a49f358627937272..766ce02f00dabdce004e866cc393c7f430630b43 100644 (file)
--- a/gst/gststructure.h
+++ b/gst/gststructure.h
@@ -32,14 +32,42 @@ G_BEGIN_DECLS
 
 typedef struct _GstStructure GstStructure;
 
+/**
+ * GstStructureForeachFunc:
+ * @field_id: the #GQuark of the field name
+ * @value: the #GValue of the field
+ * @user_data: user data
+ *
+ * A function that will be called in gst_structure_foreach()
+ *
+ * Returns: TRUE if the foreach operation should continue, FALSE if
+ * the foreach operation should stop with FALSE.
+ */
 typedef gboolean (*GstStructureForeachFunc) (GQuark   field_id,
                                             const GValue * value,
                                             gpointer user_data);
 
+/**
+ * GstStructureMapFunc:
+ * @field_id: the #GQuark of the field name
+ * @value: the #GValue of the field
+ * @user_data: user data
+ *
+ * A function that will be called in gst_structure_map_in_place()
+ *
+ * Returns: TRUE if the map operation should continue, FALSE if
+ * the map operation should stop with FALSE.
+ */
 typedef gboolean (*GstStructureMapFunc)     (GQuark   field_id,
                                             GValue * value,
                                             gpointer user_data);
 
+/**
+ * GstStructure:
+ * @type: the GType of a structure
+ *
+ * The GstStructure object. Most fields are private.
+ */
 struct _GstStructure {
   GType type;