added more documenation comments to the control library

Original commit message from CVS:
added more documenation comments to the control library

diff --git a/libs/gst/control/dparam.c b/libs/gst/control/dparam.c
index 6ca2b592071f8acafb3f42e0ae7bc615294c841c..e731bcc862fd4c76ce2b797eb644cffc7100a659 100644 (file)
--- a/libs/gst/control/dparam.c
+++ b/libs/gst/control/dparam.c
@@ -139,6 +139,8 @@ gst_dparam_init (GstDParam * dparam)
  * gst_dparam_new:
  * @type: the type that this dparam will store
  *
+ * Create a new dynamic parameter controller.
+ *
  * Returns: a new instance of GstDParam
  */
 GstDParam *
@@ -298,6 +300,8 @@ gst_dparam_dispose (GObject * object)
  * @dparam: GstDParam instance
  * @manager: the GstDParamManager that this dparam belongs to
  *
+ * Adding the parameter controller to the manager using the supplied specs and unit.
+ * See also gst_dpman_attach_dparam().
  */
 void
 gst_dparam_attach (GstDParam * dparam, GstDParamManager * manager,
@@ -328,6 +332,7 @@ gst_dparam_attach (GstDParam * dparam, GstDParamManager * manager,
  * @dparam: GstDParam instance
  * @manager: the GstDParamManager that this dparam belongs to
  *
+ * Removes a previousely added parameter controller.
  */
 void
 gst_dparam_detach (GstDParam * dparam)

diff --git a/libs/gst/control/dparammanager.c b/libs/gst/control/dparammanager.c
index c3a75e7128ddc834233dce90fcf9d73c50062360..61ce607c88fa7a1efb42bcfe7d8c771cbc6395e2 100644 (file)
--- a/libs/gst/control/dparammanager.c
+++ b/libs/gst/control/dparammanager.c
@@ -149,6 +149,8 @@ gst_dpman_init (GstDParamManager * dpman)
  * @name: name of the new #GstDParamManager instance to create
  * @parent: #GstElement which creates this instance
  *
+ * Creates a new instance of a dynamic parameter manager.
+ *
  * Returns: a new instance of #GstDParamManager.
  */
 GstDParamManager *
@@ -184,6 +186,9 @@ gst_dpman_dispose (GObject * object)
  * @update_func: callback to update the element with the new value
  * @update_data: will be included in the call to update_func
  *
+ * Add a mandatory dynamic parameter to the manager, where the value can be
+ * updated by calling the supplied callback function.
+ *
  * Returns: true if it was successfully added
  */
 gboolean
@@ -221,6 +226,9 @@ gst_dpman_add_required_dparam_callback (GstDParamManager * dpman,
  * @unit_name: the unit name of the dparam
  * @update_data: pointer to the member to be updated
  *
+ * Add a mandatory dynamic parameter to the manager, where the value can be
+ * updated by directly storing it into the provided memory location.
+ *
  * Returns: true if it was successfully added
  */
 gboolean
@@ -256,6 +264,9 @@ gst_dpman_add_required_dparam_direct (GstDParamManager * dpman,
  * @unit_name: the unit name of the dparam
  * @update_data: pointer to where the array will be stored
  *
+ * Add a mandatory dynamic parameter to the manager, where the values can be
+ * updated by storing them into the provided memory location.
+ *
  * Returns: true if it was successfully added
  */
 gboolean
@@ -289,6 +300,7 @@ gst_dpman_add_required_dparam_array (GstDParamManager * dpman,
  * @dpman: GstDParamManager instance
  * @dparam_name: the name of an existing parameter
  *
+ * Removes the named dynamic parameter from the manager.
  */
 void
 gst_dpman_remove_required_dparam (GstDParamManager * dpman,
@@ -321,6 +333,9 @@ gst_dpman_remove_required_dparam (GstDParamManager * dpman,
  * @dparam_name: a name previously added with gst_dpman_add_required_dparam
  * @dparam: GstDParam instance to attach
  *
+ * Adding a parameter controller to a dynamic parameter. Whenever the controller
+ * changes, the dynamic parameter of the GstElement will follow.
+ *
  * Returns: true if it was successfully attached
  */
 gboolean
@@ -354,6 +369,7 @@ gst_dpman_attach_dparam (GstDParamManager * dpman, const gchar * dparam_name,
  * @dpman: GstDParamManager instance
  * @dparam_name: the name of a parameter with a previously attached GstDParam
  *
+ * Removing a parameter controller from a dynamic parameter.
  */
 void
 gst_dpman_detach_dparam (GstDParamManager * dpman, const gchar * dparam_name)
@@ -377,6 +393,8 @@ gst_dpman_detach_dparam (GstDParamManager * dpman, const gchar * dparam_name)
  * @dpman: GstDParamManager instance
  * @dparam_name: the name of an existing dparam instance
  *
+ * Fetches a dparam object that is registered by manager under the given name.
+ *
  * Returns: the dparam with the given name - or NULL otherwise
  */
 GstDParam *
@@ -399,6 +417,8 @@ gst_dpman_get_dparam (GstDParamManager * dpman, const gchar * dparam_name)
  * @dpman: GstDParamManager instance
  * @dparam_name: the name of dparam
  *
+ * Fetches the type of the supplied dynamic parameter.
+ *
  * Returns: the type that this dparam requires/uses
  */
 GType
@@ -420,7 +440,9 @@ gst_dpman_get_dparam_type (GstDParamManager * dpman, const gchar * dparam_name)
  * gst_dpman_list_dparam_specs:
  * @dpman: GstDParamManager instance
  *
- * Returns: the the parameter specifications this managers maintains as a NULL terminated array
+ * Fetches the list of parameter specifications, that this manager maintains.
+ *
+ * Returns: the the parameter specifications as a NULL terminated array
  */
 GParamSpec **
 gst_dpman_list_dparam_specs (GstDParamManager * dpman)
@@ -450,6 +472,8 @@ gst_dpman_list_dparam_specs (GstDParamManager * dpman)
  * @dpman: GstDParamManager instance
  * @dparam_name: the name of dparam
  *
+ * Fetches a single parameter specification by its dparam name.
+ *
  * Returns: the the parameter specifications for a given name
  */
 GParamSpec *
@@ -469,6 +493,9 @@ gst_dpman_get_param_spec (GstDParamManager * dpman, const gchar * dparam_name)
  * gst_dpman_set_rate:
  * @dpman: GstDParamManager instance
  * @rate: the new the frame/sample rate
+ *
+ * Sets the frame or sampling rate used by the machine.
+ *
  */
 void
 gst_dpman_set_rate (GstDParamManager * dpman, gint rate)
@@ -486,6 +513,10 @@ gst_dpman_set_rate (GstDParamManager * dpman, gint rate)
  * @setupfunc: the function which initialises the mode when activated
  * @teardownfunc: the function which frees any resources the mode uses
  *
+ * Registers a run-mode for the dparam manager. Each such mode has a defined
+ * run-time behaviour - that is, they differ in the way dynamic parameter
+ * changes are pushed into the underlying GstElements.
+ * 
  */
 void
 gst_dpman_register_mode (GstDParamManagerClass * klass,
@@ -515,6 +546,8 @@ gst_dpman_register_mode (GstDParamManagerClass * klass,
  * @dpman: GstDParamManager instance
  * @modename: the name of the mode to use
  *
+ * Activate one of the registered modes.
+ *
  * Returns: TRUE if the mode was set, FALSE otherwise
  */
 gboolean
@@ -556,6 +589,7 @@ gst_dpman_set_mode (GstDParamManager * dpman, gchar * modename)
  * @dpman: GstDParamManager instance
  * @parent: the element that this GstDParamManager belongs to
  *
+ * Set a GstElement that parameters this manager should handle.
  */
 void
 gst_dpman_set_parent (GstDParamManager * dpman, GstElement * parent)
@@ -575,6 +609,8 @@ gst_dpman_set_parent (GstDParamManager * dpman, GstElement * parent)
  * gst_dpman_get_manager
  * @parent: the element that the desired GstDParamManager belongs to
  *
+ * Fetch the GstElement that parameters are handled by this manager.
+ *
  * Returns: the GstDParamManager which belongs to this element or NULL
  * if it doesn't exist
  */
@@ -619,6 +655,8 @@ gst_dpman_bypass_dparam (GstDParamManager * dpman, const gchar * dparam_name)
   }
 }
 
+// internal methods
+
 static GstDParamWrapper *
 gst_dpman_get_wrapper (GstDParamManager * dpman, const gchar * dparam_name)
 {