docs: a few small API doc fixes and additions

diff --git a/gst/gstregistry.c b/gst/gstregistry.c
index 23a86f483b5e89c622d62f5c39e450be32232b6d..67e97fecf26a3cdc06278b2c68c1c954cdc7fff5 100644 (file)
--- a/gst/gstregistry.c
+++ b/gst/gstregistry.c
@@ -933,12 +933,11 @@ gst_registry_scan_path_level (GstRegistry * registry, const gchar * path,
 
 /**
  * gst_registry_scan_path:
- * @registry: the registry to add the path to
- * @path: the path to add to the registry
+ * @registry: the registry to add found plugins to
+ * @path: the path to scan
  *
- * Add the given path to the registry. The syntax of the
- * path is specific to the registry. If the path has already been
- * added, do nothing.
+ * Scan the given path for plugins to add to the registry. The syntax of the
+ * path is specific to the registry.
  *
  * Returns: %TRUE if registry changed
  */

diff --git a/gst/gststructure.c b/gst/gststructure.c
index 4bc975f9a4d52a4c1e0d6da0e9ac8785895ccb41..8962321827980a715ada8bdde687f12c8869e01b 100644 (file)
--- a/gst/gststructure.c
+++ b/gst/gststructure.c
@@ -49,7 +49,10 @@
  * Fields can be removed with gst_structure_remove_field() or
  * gst_structure_remove_fields().
  *
- * Last reviewed on 2007-10-16 (0.10.15)
+ * Strings in structures must be ASCII or UTF-8 encoded. Other encodings are
+ * not allowed. Strings must not be empty either, but may be NULL.
+ *
+ * Last reviewed on 2009-06-08 (0.10.23)
  */
 
 #ifdef HAVE_CONFIG_H
@@ -1220,6 +1223,11 @@ gst_structure_get_fourcc (const GstStructure * structure,
  * given field.  Caller is responsible for making sure the field exists
  * and has the correct type.
  *
+ * On success @value will point to a newly-allocated copy of the date which
+ * should be freed with g_date_free() when no longer needed (note: this is
+ * inconsistent with e.g. gst_structure_get_string() which doesn't return a
+ * copy of the string).
+ *
  * 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.
@@ -1241,6 +1249,7 @@ gst_structure_get_date (const GstStructure * structure, const gchar * fieldname,
   if (!GST_VALUE_HOLDS_DATE (&field->value))
     return FALSE;
 
+  /* FIXME: 0.11 g_value_dup_boxed() -> g_value_get_boxed() */
   *value = g_value_dup_boxed (&field->value);
 
   return TRUE;

diff --git a/gst/gsttaglist.c b/gst/gsttaglist.c
index bc9678ca61cef605d654ded25819e1aa88740988..366c7ead31bb61e74a043102a6d90ae75f3b7bbc 100644 (file)
--- a/gst/gsttaglist.c
+++ b/gst/gsttaglist.c
@@ -25,7 +25,9 @@
  *
  * List of tags and values used to describe media metadata.
  *
- * Last reviewed on 2005-11-23 (0.9.5)
+ * Strings must be in ASCII or UTF-8 encoding. No other encodings are allowed.
+ *
+ * Last reviewed on 2009-06-09 (0.10.23)
  */
 
 #ifdef HAVE_CONFIG_H
@@ -1433,7 +1435,8 @@ TAG_MERGE_FUNCS (pointer, gpointer, (*value != NULL))
  * to retrieve the first string associated with this tag unmodified.
  *
  * The resulting string in @value will be in UTF-8 encoding and should be
- * freed by the caller using g_free when no longer needed.
+ * freed by the caller using g_free when no longer needed. Since 0.10.24 the
+ * returned string is also guaranteed to be non-NULL and non-empty.
  *
  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
  *              given list.
@@ -1449,7 +1452,8 @@ TAG_MERGE_FUNCS (pointer, gpointer, (*value != NULL))
  * list.
  *
  * The resulting string in @value will be in UTF-8 encoding and should be
- * freed by the caller using g_free when no longer needed.
+ * freed by the caller using g_free when no longer needed. Since 0.10.24 the
+ * returned string is also guaranteed to be non-NULL and non-empty.
  *
  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
  *              given list.