another shell oneliner for empty return value docs more doc fixes (parameters and return values)

Original commit message from CVS:
another shell oneliner for empty return value docs
more doc fixes (parameters and return values)

ChangeLog

@@ -1,3 +1,12 @@
+2005-01-05  Stefan Kost  <ensonic@users.sf.net>
+
+	* docs/README:
+    another shell oneliner for empty return value docs
+	* gst/gstcaps.c:
+	* gst/gstvalue.c:
+	* libs/gst/control/dparam.c:
+    more doc fixes (parameters and return values)
+
 2005-01-05  Vincent Torri  <torri@iecn.u-nancy.fr>
 
 	Reviewed by:  Ronald S. Bultje  <rbultje@ronald.bitfreak.net>

docs/README

@@ -138,7 +138,10 @@ GTK-DOC NOTES
     with the types in XXX.types to detect entries that
     are maybe missing
   - gtk docs does not warns about empty member docs!, run
-    find . -name "*.[c,h]" -exec egrep -Hn "^ +\* +@.*: *$" {} \; | wc -l
+    find . -name "*.[c,h]" -exec egrep -Hn "^ +\* +@.*: *$" {} \;
+    in the project root to find them
+  - gtk docs does not warns about empty Returns: docs!, run
+    find . -name "*.[c,h]" -exec egrep -Hn "^ +\* +@Returns: *$" {} \;
     in the project root to find them
 
 * what happens during a gtk-doc build ?

gst/gstcaps.c

@@ -361,11 +361,11 @@ gst_caps_remove_structure (GstCaps * caps, guint idx)
 
 /**
  * gst_caps_split_one:
- * @caps: 
+ * @caps: a #GstCaps
  *
  * This function is not implemented.
  *
- * Returns:
+ * Returns: NULL
  */
 GstCaps *
 gst_caps_split_one (GstCaps * caps)

gst/gstvalue.c

@@ -2249,9 +2249,11 @@ gst_value_register (const GstValueTable * table)
 
 /**
  * gst_value_init_and_copy:
- * @dest:
- * @src:
+ * @dest: the target value
+ * @src: the source value
  *
+ * Initialises the target value to be of the same type as source and then copies
+ * the contents from source to target.
  */
 void
 gst_value_init_and_copy (GValue * dest, const GValue * src)

libs/gst/control/dparam.c

@@ -247,10 +247,10 @@ gst_dparam_set_property (GObject * object, guint prop_id, const GValue * value,
 
 /**
  * gst_dparam_do_update_default:
- * @dparam: 
- * @timestamp:
- * @value:
- * @update_info:
+ * @dparam: the parameter to update
+ * @timestamp: when should the update take place
+ * @value: the new value
+ * @update_info: unused here
  *
  * Default implementation for changing a dynamic parameter.
  * Subclasses might overwrite the behaviour of this.

libs/gst/control/dparammanager.c

@@ -205,7 +205,10 @@ gst_dpman_add_required_dparam_callback (GstDParamManager * dpman,
   dpwrap =
       gst_dpman_new_wrapper (dpman, param_spec, unit_name, GST_DPMAN_CALLBACK);
 
-  g_return_val_if_fail (dpwrap != NULL, FALSE);
+  if (!dpwrap) {
+    GST_INFO ("failed to obtain a new dparam wrapper");
+    return FALSE;
+  }
 
   GST_DEBUG ("adding required callback dparam '%s'",
       g_param_spec_get_name (param_spec));
@@ -244,7 +247,10 @@ gst_dpman_add_required_dparam_direct (GstDParamManager * dpman,
   dpwrap =
       gst_dpman_new_wrapper (dpman, param_spec, unit_name, GST_DPMAN_DIRECT);
 
-  g_return_val_if_fail (dpwrap != NULL, FALSE);
+  if (!dpwrap) {
+    GST_INFO ("failed to obtain a new dparam wrapper");
+    return FALSE;
+  }
 
   GST_DEBUG ("adding required direct dparam '%s'",
       g_param_spec_get_name (param_spec));
@@ -282,7 +288,10 @@ gst_dpman_add_required_dparam_array (GstDParamManager * dpman,
   dpwrap =
       gst_dpman_new_wrapper (dpman, param_spec, unit_name, GST_DPMAN_ARRAY);
 
-  g_return_val_if_fail (dpwrap != NULL, FALSE);
+  if (!dpwrap) {
+    GST_INFO ("failed to obtain a new dparam wrapper");
+    return FALSE;
+  }
 
   GST_DEBUG ("adding required array dparam '%s'",
       g_param_spec_get_name (param_spec));
@@ -353,7 +362,12 @@ gst_dpman_attach_dparam (GstDParamManager * dpman, const gchar * dparam_name,
 
   dpwrap = gst_dpman_get_wrapper (dpman, dparam_name);
 
-  g_return_val_if_fail (dpwrap != NULL, FALSE);
+  if (!dpwrap) {
+    GST_INFO ("failed to obtain get the dparam wrapper for parameter '%s'",
+        dparam_name);
+    return FALSE;
+  }
+  // FIXME: if these are triggered convert them to messages + returns as well
   g_return_val_if_fail (dpwrap->value != NULL, FALSE);
   g_return_val_if_fail (G_PARAM_SPEC_VALUE_TYPE (dpwrap->param_spec) ==
       GST_DPARAM_TYPE (dparam), FALSE);
@@ -407,7 +421,12 @@ gst_dpman_get_dparam (GstDParamManager * dpman, const gchar * dparam_name)
   g_return_val_if_fail (dparam_name != NULL, NULL);
 
   dpwrap = gst_dpman_get_wrapper (dpman, dparam_name);
-  g_return_val_if_fail (dpwrap != NULL, NULL);
+
+  if (!dpwrap) {
+    GST_INFO ("failed to obtain get the dparam wrapper for parameter '%s'",
+        dparam_name);
+    return NULL;
+  }
 
   return dpwrap->dparam;
 }
@@ -431,7 +450,12 @@ gst_dpman_get_dparam_type (GstDParamManager * dpman, const gchar * dparam_name)
   g_return_val_if_fail (dparam_name != NULL, 0);
 
   dpwrap = gst_dpman_get_wrapper (dpman, dparam_name);
-  g_return_val_if_fail (dpwrap != NULL, 0);
+
+  if (!dpwrap) {
+    GST_INFO ("failed to obtain get the dparam wrapper for parameter '%s'",
+        dparam_name);
+    return 0;
+  }
 
   return G_VALUE_TYPE (dpwrap->value);
 }