ALSA: kernel docs: fix sound/core/ kernel-doc

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@oracle.com>
Signed-off-by: Takashi Iwai <tiwai@suse.de>

1 files changed, 8 insertions, 16 deletions

diff --git a/sound/core/pcm_native.c b/sound/core/pcm_native.c
index e61e12506ded..aef18682c035 100644
--- a/sound/core/pcm_native.c
+++ b/sound/core/pcm_native.c
@@ -875,10 +875,8 @@ static struct action_ops snd_pcm_action_start = {
 };
 
 /**
- * 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_stop = {
 };
 
 /**
- * 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_substream *substream, int state)
 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_suspend = {
 };
 
 /**
- * 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_substream *substream)
 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_prepare = {
 };
 
 /**
- * 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)