gst-libs/gst/: Add gtk-doc style comments. Also fix a function name.

Original commit message from CVS:
2004-01-25  Ronald Bultje  <rbultje@ronald.bitfreak.net>

* gst-libs/gst/mixer/mixer.c:
* gst-libs/gst/propertyprobe/propertyprobe.c:
* gst-libs/gst/tuner/tuner.c: (gst_tuner_find_norm_by_name),
(gst_tuner_find_channel_by_name):
* gst-libs/gst/tuner/tuner.h:
Add gtk-doc style comments. Also fix a function name.

4 files changed, 248 insertions, 3 deletions

diff --git a/gst-libs/gst/mixer/mixer.c b/gst-libs/gst/mixer/mixer.c
index 7412ca28..b0a9465d 100644
--- a/gst-libs/gst/mixer/mixer.c
+++ b/gst-libs/gst/mixer/mixer.c
@@ -106,6 +106,18 @@ gst_mixer_class_init (GstMixerClass *klass)
   klass->set_record = NULL;
 }
 
+/**
+ *agst_mixer_list_tracks:
+ * @mixer: the #GstMixer (a #GstElement) to get the tracks from.
+ *
+ * Returns a list of avialable tracks for this mixer/element. Note
+ * that it is allowed for sink (output) elements to only provide
+ * the output tracks in this list. Likewise, for sources (inputs),
+ * it is allowed to only provide input elements in this list.
+ *
+ * Returns: A #GList consisting of zero or more #GstMixerTracks.
+ */
+
 const GList *
 gst_mixer_list_tracks (GstMixer *mixer)
 {
@@ -118,6 +130,21 @@ gst_mixer_list_tracks (GstMixer *mixer)
   return NULL;
 }
 
+/**
+ * gst_mixer_set_volume:
+ * @mixer: The #GstMixer (a #GstElement) that owns the track.
+ * @track: The #GstMixerTrack to set the volume on.
+ * @volumes: an array of integers (of size track->num_channels)
+ *           that gives the wanted volume for each channel in
+ *           this track.
+ *
+ * Sets the volume on each channel in a track. Short note about
+ * naming: a track is defined as one separate stream owned by
+ * the mixer/element, such as 'Line-in' or 'Microphone'. A
+ * channel is said to be a mono-stream inside this track. A
+ * stereo track thus contains two channels.
+ */
+
 void
 gst_mixer_set_volume (GstMixer      *mixer,
 		      GstMixerTrack *track,
@@ -130,6 +157,17 @@ gst_mixer_set_volume (GstMixer      *mixer,
   }
 }
 
+/*
+ * gst_mixer_get_volume:
+ * @mixer: the #GstMixer (a #GstElement) that owns the track
+ * @track: the GstMixerTrack to get the volume from.
+ * @volumes: a pre-allocated array of integers (of size
+ *           track->num_channels) to store the current volume
+ *           of each channel in the given track in.
+ *
+ * Get the current volume(s) on the given track.
+ */
+
 void
 gst_mixer_get_volume (GstMixer      *mixer,
 		      GstMixerTrack *track,
@@ -148,6 +186,17 @@ gst_mixer_get_volume (GstMixer      *mixer,
   }
 }
 
+/**
+ * gst_mixer_set_mute:
+ * @mixer: the #GstMixer (a #GstElement) that owns the track.
+ * @track: the #GstMixerTrack to operate on.
+ * @mute: a boolean value indicating whether to turn on or off
+ *        muting.
+ *
+ * Mutes or unmutes the given channel. To find out whether a
+ * track is currently muted, use GST_MIXER_TRACK_HAS_FLAG ().
+ */
+
 void
 gst_mixer_set_mute (GstMixer      *mixer,
 		    GstMixerTrack *track,
@@ -160,6 +209,19 @@ gst_mixer_set_mute (GstMixer      *mixer,
   }
 }
 
+/**
+ * gst_mixer_set_record:
+ * @mixer: The #GstMixer (a #GstElement) that owns the track.
+ * @track: the #GstMixerTrack to operate on.
+ * @record: a boolean value that indicates whether to turn on
+ *          or off recording.
+ *
+ * Enables or disables recording on the given track. Note that
+ * this is only possible on input tracks, not on output tracks
+ * (see GST_MIXER_TRACK_HAS_FLAG () and the GST_MIXER_TRACK_INPUT
+ * flag).
+ */
+
 void
 gst_mixer_set_record (GstMixer      *mixer,
 		      GstMixerTrack *track,
diff --git a/gst-libs/gst/propertyprobe/propertyprobe.c b/gst-libs/gst/propertyprobe/propertyprobe.c
index a8de4a9a..ea242430 100644
--- a/gst-libs/gst/propertyprobe/propertyprobe.c
+++ b/gst-libs/gst/propertyprobe/propertyprobe.c
@@ -82,6 +82,16 @@ gst_property_probe_iface_init (GstPropertyProbeInterface *iface)
   iface->get_values     = NULL;
 }
 
+/**
+ * gst_property_probe_get_properties:
+ * @probe: the #GstPropertyProbe to get the properties for.
+ *
+ * Get a list of properties for which probing is supported.
+ *
+ * Returns the list of properties for which probing is supported
+ * by this element.
+ */
+
 const GList *
 gst_property_probe_get_properties (GstPropertyProbe *probe)
 {
@@ -133,6 +143,18 @@ gst_property_probe_probe_property (GstPropertyProbe *probe,
     iface->probe_property (probe, pspec->param_id, pspec);
 }
 
+/**
+ * gst_property_probe_probe_property_name:
+ * @probe: the #GstPropertyProbe to check.
+ * @name: name of the property to return.
+ *
+ * Returns the #GParamSpec for the given property. It's similar to
+ * g_object_class_find_property (), except that this function only
+ * takes "probe'able" properties into account.
+ *
+ * Returns: the #GParamSpec that belongs to the given property.
+ */
+
 void
 gst_property_probe_probe_property_name (GstPropertyProbe *probe,
 					const gchar      *name)
@@ -151,6 +173,20 @@ gst_property_probe_probe_property_name (GstPropertyProbe *probe,
   gst_property_probe_probe_property (probe, pspec);
 }
 
+/**
+ * gst_property_probe_needs_probe:
+ * @probe: the #GstPropertyProbe object to which the given property belongs.
+ * @pspec: a #GParamSpec that identifies the property to check.
+ *
+ * Checks whether a property needs a probe. This might be because
+ * the property wasn't initialized before, or because host setup
+ * changed. This might be, for example, because a new device was
+ * added, and thus device probing needs to be refreshed to display
+ * the new device.
+ *
+ * Returns: TRUE if the property needs a new probe, FALSE if not.
+ */
+
 gboolean
 gst_property_probe_needs_probe (GstPropertyProbe *probe,
 				const GParamSpec *pspec)
@@ -168,6 +204,16 @@ gst_property_probe_needs_probe (GstPropertyProbe *probe,
   return FALSE;
 }
 
+/**
+ * gst_property_probe_needs_probe_name:
+ * @probe: the #GstPropertyProbe object to which the given property belongs.
+ * @name: the name of the property to check.
+ *
+ * Same as gst_property_probe_needs_probe ().
+ *
+ * Returns: TRUE if the property needs a new probe, FALSE if not.
+ */
+
 gboolean
 gst_property_probe_needs_probe_name (GstPropertyProbe *probe,
 				     const gchar      *name)
@@ -185,6 +231,17 @@ gst_property_probe_needs_probe_name (GstPropertyProbe *probe,
 
   return gst_property_probe_needs_probe (probe, pspec);
 }
+
+/**
+ * gst_property_probe_get_values:
+ * @probe: the #GstPropertyProbe object.
+ * @pspec: the #GParamSpec property identifier.
+ *
+ * Gets the possible (probed) values for the given property,
+ * requires the property to have been probed before.
+ *
+ * Returns: A list of valid values for the given property.
+ */
                                                                                
 GValueArray *
 gst_property_probe_get_values (GstPropertyProbe *probe,
@@ -203,6 +260,16 @@ gst_property_probe_get_values (GstPropertyProbe *probe,
   return NULL;
 }
 
+/**
+ * gst_property_probe_get_values_name:
+ * @probe: the #GstPropertyProbe object.
+ * @name: the name of the property to get values for.
+ *
+ * Same as gst_property_probe_get_values ().
+ *
+ * Returns: A list of valid values for the given property.
+ */
+
 GValueArray *
 gst_property_probe_get_values_name (GstPropertyProbe *probe,
 				    const gchar      *name)
@@ -221,6 +288,17 @@ gst_property_probe_get_values_name (GstPropertyProbe *probe,
   return gst_property_probe_get_values (probe, pspec);
 }
 
+/**
+ * gst_property_probe_probe_and_get_values:
+ * @probe: the #GstPropertyProbe object.
+ * @pspec: The #GParamSpec property identifier.
+ *
+ * Check whether the given property requires a new probe. If so,
+ * fo the probe. After that, retrieve a value list. Meant as a
+ * utility function that wraps the above functions.
+ *
+ * Return: the list of valid values for this property.
+ */
 
 GValueArray *
 gst_property_probe_probe_and_get_values (GstPropertyProbe *probe,
@@ -239,6 +317,16 @@ gst_property_probe_probe_and_get_values (GstPropertyProbe *probe,
   return gst_property_probe_get_values (probe, pspec);
 }
 
+/**
+ * gst_property_probe_probe_and_get_values_name:
+ * @probe: the #GstPropertyProbe object.
+ * @name: the name of the property to get values for.
+ *
+ * Same as gst_property_probe_probe_and_get_values ().
+ *
+ * Return: the list of valid values for this property.
+ */
+
 GValueArray *
 gst_property_probe_probe_and_get_values_name (GstPropertyProbe *probe,
 					      const gchar      *name)
diff --git a/gst-libs/gst/tuner/tuner.c b/gst-libs/gst/tuner/tuner.c
index cc41402c..471fc5d2 100644
--- a/gst-libs/gst/tuner/tuner.c
+++ b/gst-libs/gst/tuner/tuner.c
@@ -120,6 +120,16 @@ gst_tuner_class_init (GstTunerClass *klass)
   klass->signal_strength = NULL;
 }
 
+/**
+ * gst_tuner_list_channels:
+ * @tuner: the #GstTuner (a #GstElement) to get the channels from.
+ *
+ * Retrieve a list of channels (e.g. 'composite', 's-video', ...)
+ * from the given tuner object.
+ *
+ * Returns: a list of channels available on this tuner.
+ */
+
 const GList *
 gst_tuner_list_channels (GstTuner *tuner)
 {
@@ -132,6 +142,14 @@ gst_tuner_list_channels (GstTuner *tuner)
   return NULL;
 }
 
+/**
+ * gst_tuner_set_channel:
+ * @tuner: the #GstTuner (a #GstElement) that owns the channel.
+ * @channel: the channel to tune to.
+ *
+ * Tunes the object to the given channel.
+ */
+
 void
 gst_tuner_set_channel (GstTuner        *tuner,
 		       GstTunerChannel *channel)
@@ -143,6 +161,15 @@ gst_tuner_set_channel (GstTuner        *tuner,
   }
 }
 
+/**
+ * gst_Tuner_get_channel:
+ * @tuner: the #GstTuner (a #GstElement) to get the current channel from.
+ *
+ * Retrieve the current channel from the tuner.
+ *
+ * Returns: the current channel of the tuner object.
+ */
+
 GstTunerChannel *
 gst_tuner_get_channel (GstTuner *tuner)
 {
@@ -155,6 +182,17 @@ gst_tuner_get_channel (GstTuner *tuner)
   return NULL;
 }
 
+/**
+ * gst_tuner_get_norms_list:
+ * @tuner: the #GstTuner (*a #GstElement) to get the list of norms from.
+ *
+ * Retrieve a list of available norms on the currently tuned channel
+ * from the given tuner object.
+ *
+ * Returns: A list of norms available on the current channel for this
+ *          tuner object.
+ */
+
 const GList *
 gst_tuner_list_norms (GstTuner *tuner)
 {
@@ -167,6 +205,14 @@ gst_tuner_list_norms (GstTuner *tuner)
   return NULL;
 }
 
+/**
+ * gst_tuner_set_norm:
+ * @tuner: the #GstTuner (a #GstElement) to set the norm on.
+ * @norm: the norm to use for the current channel.
+ *
+ * Changes the video norm on this tuner to the given norm.
+ */
+
 void
 gst_tuner_set_norm (GstTuner     *tuner,
 		    GstTunerNorm *norm)
@@ -178,6 +224,16 @@ gst_tuner_set_norm (GstTuner     *tuner,
   }
 }
 
+/**
+ * gst_tuner_get_norm:
+ * @tuner: the #GstTuner (a #GstElement) to get the current norm from.
+ *
+ * Get the current video norm from the given tuner object for the
+ * currently selected channel.
+ *
+ * Returns: the current norm.
+ */
+
 GstTunerNorm *
 gst_tuner_get_norm (GstTuner *tuner)
 {
@@ -190,6 +246,18 @@ gst_tuner_get_norm (GstTuner *tuner)
   return NULL;
 }
 
+/**
+ * gst_tuner_set_frequency:
+ * @tuner: the #Gsttuner (a #GstElement) that owns the given channel.
+ * @channel: the #GstTunerChannel to set the frequency on.
+ * @frequency: the frequency to tune in to.
+ *
+ * Sets a tuning frequency on the given tuner/channel. Note that this
+ * requires the given channel to be a "tuning" channel, which can be
+ * checked using GST_TUNER_CHANNEL_HAS_FLAG (), with the proper flag
+ * being GST_TUNER_CHANNEL_FREQUENCY.
+ */
+
 void
 gst_tuner_set_frequency (GstTuner        *tuner,
 			 GstTunerChannel *channel,
@@ -205,6 +273,17 @@ gst_tuner_set_frequency (GstTuner        *tuner,
   }
 }
 
+/**
+ * gst_tuner_get_frequency:
+ * @tuner: the #GstTuner (a #GstElement) that owns the given channel.
+ * @channel: the #GstTunerChannel to retrieve the frequency from.
+ *
+ * Retrieve the current frequency from the given channel. The same
+ * applies as for set_frequency (): check the flag.
+ *
+ * Returns: the current frequency, or 0 on error.
+ */
+
 gulong
 gst_tuner_get_frequency (GstTuner        *tuner,
 			 GstTunerChannel *channel)
@@ -221,6 +300,20 @@ gst_tuner_get_frequency (GstTuner        *tuner,
   return 0;
 }
 
+/**
+ * gst_tuner_get_signal_strength:
+ * @tuner: the #GstTuner (a #GstElement) that owns the given channel.
+ * @channel: the #GstTunerChannel to get the signal strength from.
+ *
+ * get the strength of the signal on this channel. Note that this
+ * requires the current channel to be a "tuning" channel, e.g. a
+ * channel on which frequency can be set. This can be checked using
+ * GST_TUNER_CHANNEL_HAS_FLAG (), and the appropriate flag to check
+ * for is GST_TUNER_CHANNEL_FREQUENCY.
+ *
+ * Returns: signal strength, or 0 on error.
+ */
+
 gint
 gst_tuner_signal_strength (GstTuner        *tuner,
 			   GstTunerChannel *channel)
@@ -238,7 +331,8 @@ gst_tuner_signal_strength (GstTuner        *tuner,
 }
 
 GstTunerNorm *
-gst_tuner_find_norm_by_name (GstTuner *tuner, gchar *norm)
+gst_tuner_find_norm_by_name (GstTuner *tuner,
+			     gchar    *norm)
 {
   GList *walk;
 
@@ -255,7 +349,8 @@ gst_tuner_find_norm_by_name (GstTuner *tuner, gchar *norm)
 }
 
 GstTunerChannel *
-gst_v4l2_find_channel_by_name (GstTuner *tuner, gchar *channel)
+gst_tuner_find_channel_by_name (GstTuner *tuner,
+				gchar    *channel)
 {
   GList *walk;
 
diff --git a/gst-libs/gst/tuner/tuner.h b/gst-libs/gst/tuner/tuner.h
index de02051a..11a27cc4 100644
--- a/gst-libs/gst/tuner/tuner.h
+++ b/gst-libs/gst/tuner/tuner.h
@@ -106,7 +106,7 @@ gint		gst_tuner_signal_strength	(GstTuner        *tuner,
 /* helper functions */
 GstTunerNorm *	gst_tuner_find_norm_by_name	(GstTuner	 *tuner,
 						 gchar		 *norm);
-GstTunerChannel * gst_tuner_find_channel_by_name(GstTuner	 *tuner,
+GstTunerChannel *gst_tuner_find_channel_by_name (GstTuner	 *tuner,
 						 gchar		 *channel);
 
 /* trigger signals */