[alsa-devel] [PATCH] kernel docs: fix sound/core/ kernel-doc
Takashi Iwai
tiwai at suse.de
Thu Oct 16 08:54:50 CEST 2008
At Wed, 15 Oct 2008 14:38:40 -0700,
Randy Dunlap wrote:
>
> From: Randy Dunlap <randy.dunlap at oracle.com>
>
> Add kernel-doc function short descriptions to sound/core functions that
> are missing this short description. Mostly this involves moving some of
> the function description onto the @funcname line.
>
> Also correct a few variable names and fix other kernel-doc notation.
>
> Signed-off-by: Randy Dunlap <randy.dunlap at oracle.com>
> cc: Jaroslav Kysela <perex at perex.cz>
> cc: Takashi Iwai <tiwai at suse.de>
Thanks, applied now. I'll include it in the next pull request.
Takashi
> ---
> sound/core/pcm_lib.c | 48 ++++++++++++++++++++++++------------------------
> sound/core/pcm_native.c | 24 ++++++++----------------
> 2 files changed, 32 insertions(+), 40 deletions(-)
>
> --- lin2627-g5-kdoc.orig/sound/core/pcm_lib.c
> +++ lin2627-g5-kdoc/sound/core/pcm_lib.c
> @@ -908,12 +908,12 @@ int snd_pcm_hw_rule_add(struct snd_pcm_r
> EXPORT_SYMBOL(snd_pcm_hw_rule_add);
>
> /**
> - * snd_pcm_hw_constraint_mask
> + * snd_pcm_hw_constraint_mask - apply the given bitmap mask constraint
> * @runtime: PCM runtime instance
> * @var: hw_params variable to apply the mask
> * @mask: the bitmap mask
> *
> - * Apply the constraint of the given bitmap mask to a mask parameter.
> + * Apply the constraint of the given bitmap mask to a 32-bit mask parameter.
> */
> int snd_pcm_hw_constraint_mask(struct snd_pcm_runtime *runtime, snd_pcm_hw_param_t var,
> u_int32_t mask)
> @@ -928,12 +928,12 @@ int snd_pcm_hw_constraint_mask(struct sn
> }
>
> /**
> - * snd_pcm_hw_constraint_mask64
> + * snd_pcm_hw_constraint_mask64 - apply the given bitmap mask constraint
> * @runtime: PCM runtime instance
> * @var: hw_params variable to apply the mask
> * @mask: the 64bit bitmap mask
> *
> - * Apply the constraint of the given bitmap mask to a mask parameter.
> + * Apply the constraint of the given bitmap mask to a 64-bit mask parameter.
> */
> int snd_pcm_hw_constraint_mask64(struct snd_pcm_runtime *runtime, snd_pcm_hw_param_t var,
> u_int64_t mask)
> @@ -949,7 +949,7 @@ int snd_pcm_hw_constraint_mask64(struct
> }
>
> /**
> - * snd_pcm_hw_constraint_integer
> + * snd_pcm_hw_constraint_integer - apply an integer constraint to an interval
> * @runtime: PCM runtime instance
> * @var: hw_params variable to apply the integer constraint
> *
> @@ -964,7 +964,7 @@ int snd_pcm_hw_constraint_integer(struct
> EXPORT_SYMBOL(snd_pcm_hw_constraint_integer);
>
> /**
> - * snd_pcm_hw_constraint_minmax
> + * snd_pcm_hw_constraint_minmax - apply a min/max range constraint to an interval
> * @runtime: PCM runtime instance
> * @var: hw_params variable to apply the range
> * @min: the minimal value
> @@ -995,7 +995,7 @@ static int snd_pcm_hw_rule_list(struct s
>
>
> /**
> - * snd_pcm_hw_constraint_list
> + * snd_pcm_hw_constraint_list - apply a list of constraints to a parameter
> * @runtime: PCM runtime instance
> * @cond: condition bits
> * @var: hw_params variable to apply the list constraint
> @@ -1031,7 +1031,7 @@ static int snd_pcm_hw_rule_ratnums(struc
> }
>
> /**
> - * snd_pcm_hw_constraint_ratnums
> + * snd_pcm_hw_constraint_ratnums - apply ratnums constraint to a parameter
> * @runtime: PCM runtime instance
> * @cond: condition bits
> * @var: hw_params variable to apply the ratnums constraint
> @@ -1064,7 +1064,7 @@ static int snd_pcm_hw_rule_ratdens(struc
> }
>
> /**
> - * snd_pcm_hw_constraint_ratdens
> + * snd_pcm_hw_constraint_ratdens - apply ratdens constraint to a parameter
> * @runtime: PCM runtime instance
> * @cond: condition bits
> * @var: hw_params variable to apply the ratdens constraint
> @@ -1095,7 +1095,7 @@ static int snd_pcm_hw_rule_msbits(struct
> }
>
> /**
> - * snd_pcm_hw_constraint_msbits
> + * snd_pcm_hw_constraint_msbits - add a hw constraint msbits rule
> * @runtime: PCM runtime instance
> * @cond: condition bits
> * @width: sample bits width
> @@ -1123,7 +1123,7 @@ static int snd_pcm_hw_rule_step(struct s
> }
>
> /**
> - * snd_pcm_hw_constraint_step
> + * snd_pcm_hw_constraint_step - add a hw constraint step rule
> * @runtime: PCM runtime instance
> * @cond: condition bits
> * @var: hw_params variable to apply the step constraint
> @@ -1154,7 +1154,7 @@ static int snd_pcm_hw_rule_pow2(struct s
> }
>
> /**
> - * snd_pcm_hw_constraint_pow2
> + * snd_pcm_hw_constraint_pow2 - add a hw constraint power-of-2 rule
> * @runtime: PCM runtime instance
> * @cond: condition bits
> * @var: hw_params variable to apply the power-of-2 constraint
> @@ -1202,13 +1202,13 @@ void _snd_pcm_hw_params_any(struct snd_p
> EXPORT_SYMBOL(_snd_pcm_hw_params_any);
>
> /**
> - * snd_pcm_hw_param_value
> + * snd_pcm_hw_param_value - return @params field @var value
> * @params: the hw_params instance
> * @var: parameter to retrieve
> - * @dir: pointer to the direction (-1,0,1) or NULL
> + * @dir: pointer to the direction (-1,0,1) or %NULL
> *
> - * Return the value for field PAR if it's fixed in configuration space
> - * defined by PARAMS. Return -EINVAL otherwise
> + * Return the value for field @var if it's fixed in configuration space
> + * defined by @params. Return -%EINVAL otherwise.
> */
> int snd_pcm_hw_param_value(const struct snd_pcm_hw_params *params,
> snd_pcm_hw_param_t var, int *dir)
> @@ -1271,13 +1271,13 @@ static int _snd_pcm_hw_param_first(struc
>
>
> /**
> - * snd_pcm_hw_param_first
> + * snd_pcm_hw_param_first - refine config space and return minimum value
> * @pcm: PCM instance
> * @params: the hw_params instance
> * @var: parameter to retrieve
> - * @dir: pointer to the direction (-1,0,1) or NULL
> + * @dir: pointer to the direction (-1,0,1) or %NULL
> *
> - * Inside configuration space defined by PARAMS remove from PAR all
> + * Inside configuration space defined by @params remove from @var all
> * values > minimum. Reduce configuration space accordingly.
> * Return the minimum.
> */
> @@ -1317,13 +1317,13 @@ static int _snd_pcm_hw_param_last(struct
>
>
> /**
> - * snd_pcm_hw_param_last
> + * snd_pcm_hw_param_last - refine config space and return maximum value
> * @pcm: PCM instance
> * @params: the hw_params instance
> * @var: parameter to retrieve
> - * @dir: pointer to the direction (-1,0,1) or NULL
> + * @dir: pointer to the direction (-1,0,1) or %NULL
> *
> - * Inside configuration space defined by PARAMS remove from PAR all
> + * Inside configuration space defined by @params remove from @var all
> * values < maximum. Reduce configuration space accordingly.
> * Return the maximum.
> */
> @@ -1345,11 +1345,11 @@ int snd_pcm_hw_param_last(struct snd_pcm
> EXPORT_SYMBOL(snd_pcm_hw_param_last);
>
> /**
> - * snd_pcm_hw_param_choose
> + * snd_pcm_hw_param_choose - choose a configuration defined by @params
> * @pcm: PCM instance
> * @params: the hw_params instance
> *
> - * Choose one configuration from configuration space defined by PARAMS
> + * Choose one configuration from configuration space defined by @params.
> * The configuration chosen is that obtained fixing in this order:
> * first access, first format, first subformat, min channels,
> * min rate, min period time, max buffer size, min tick time
> --- lin2627-g5-kdoc.orig/sound/core/pcm_native.c
> +++ lin2627-g5-kdoc/sound/core/pcm_native.c
> @@ -875,10 +875,8 @@ static struct action_ops snd_pcm_action_
> };
>
> /**
> - * snd_pcm_start
> + * snd_pcm_start - start all linked streams
> * @substream: the PCM substream instance
> - *
> - * Start all linked streams.
> */
> int snd_pcm_start(struct snd_pcm_substream *substream)
> {
> @@ -926,12 +924,11 @@ static struct action_ops snd_pcm_action_
> };
>
> /**
> - * snd_pcm_stop
> + * snd_pcm_stop - try to stop all running streams in the substream group
> * @substream: the PCM substream instance
> * @state: PCM state after stopping the stream
> *
> - * Try to stop all running streams in the substream group.
> - * The state of each stream is changed to the given value after that unconditionally.
> + * The state of each stream is then changed to the given state unconditionally.
> */
> int snd_pcm_stop(struct snd_pcm_substream *substream, int state)
> {
> @@ -941,11 +938,10 @@ int snd_pcm_stop(struct snd_pcm_substrea
> EXPORT_SYMBOL(snd_pcm_stop);
>
> /**
> - * snd_pcm_drain_done
> + * snd_pcm_drain_done - stop the DMA only when the given stream is playback
> * @substream: the PCM substream
> *
> - * Stop the DMA only when the given stream is playback.
> - * The state is changed to SETUP.
> + * After stopping, the state is changed to SETUP.
> * Unlike snd_pcm_stop(), this affects only the given stream.
> */
> int snd_pcm_drain_done(struct snd_pcm_substream *substream)
> @@ -1065,10 +1061,9 @@ static struct action_ops snd_pcm_action_
> };
>
> /**
> - * snd_pcm_suspend
> + * snd_pcm_suspend - trigger SUSPEND to all linked streams
> * @substream: the PCM substream
> *
> - * Trigger SUSPEND to all linked streams.
> * After this call, all streams are changed to SUSPENDED state.
> */
> int snd_pcm_suspend(struct snd_pcm_substream *substream)
> @@ -1088,10 +1083,9 @@ int snd_pcm_suspend(struct snd_pcm_subst
> EXPORT_SYMBOL(snd_pcm_suspend);
>
> /**
> - * snd_pcm_suspend_all
> + * snd_pcm_suspend_all - trigger SUSPEND to all substreams in the given pcm
> * @pcm: the PCM instance
> *
> - * Trigger SUSPEND to all substreams in the given pcm.
> * After this call, all streams are changed to SUSPENDED state.
> */
> int snd_pcm_suspend_all(struct snd_pcm *pcm)
> @@ -1313,11 +1307,9 @@ static struct action_ops snd_pcm_action_
> };
>
> /**
> - * snd_pcm_prepare
> + * snd_pcm_prepare - prepare the PCM substream to be triggerable
> * @substream: the PCM substream instance
> * @file: file to refer f_flags
> - *
> - * Prepare the PCM substream to be triggerable.
> */
> static int snd_pcm_prepare(struct snd_pcm_substream *substream,
> struct file *file)
> _______________________________________________
> Alsa-devel mailing list
> Alsa-devel at alsa-project.org
> http://mailman.alsa-project.org/mailman/listinfo/alsa-devel
>
More information about the Alsa-devel
mailing list