ALSA: core: Fix missing return value comments for kernel docs

Each kernel doc comment expects the definition of the return value in
a proper format.  This patch adds or fixes the missing entries for the
remaining ALSA core API functions.

Link: https://lore.kernel.org/r/20220713104759.4365-8-tiwai@suse.de
Signed-off-by: Takashi Iwai <tiwai@suse.de>

5 files changed, 18 insertions, 2 deletions

diff --git a/sound/core/device.c b/sound/core/device.c
index bf0b04a7ee79..b57d80a17052 100644
--- a/sound/core/device.c
+++ b/sound/core/device.c
@@ -247,6 +247,8 @@ void snd_device_free_all(struct snd_card *card)
  * device, either @SNDRV_DEV_BUILD, @SNDRV_DEV_REGISTERED or
  * @SNDRV_DEV_DISCONNECTED is returned.
  * Or for a non-existing device, -1 is returned as an error.
+ *
+ * Return: the current state, or -1 if not found
  */
 int snd_device_get_state(struct snd_card *card, void *device_data)
 {
diff --git a/sound/core/info.c b/sound/core/info.c
index 782fba87cc04..b8058b341178 100644
--- a/sound/core/info.c
+++ b/sound/core/info.c
@@ -868,6 +868,8 @@ EXPORT_SYMBOL(snd_info_register);
  *
  * This proc file entry will be registered via snd_card_register() call, and
  * it will be removed automatically at the card removal, too.
+ *
+ * Return: zero if successful, or a negative error code
  */
 int snd_card_rw_proc_new(struct snd_card *card, const char *name,
 			 void *private_data,
diff --git a/sound/core/init.c b/sound/core/init.c
index 1870aee7b64f..3ac95c66a4b5 100644
--- a/sound/core/init.c
+++ b/sound/core/init.c
@@ -215,6 +215,8 @@ static void __snd_card_release(struct device *dev, void *data)
  * via snd_card_free() call in the error; otherwise it may lead to UAF due to
  * devres call orders.  You can use snd_card_free_on_error() helper for
  * handling it more easily.
+ *
+ * Return: zero if successful, or a negative error code
  */
 int snd_devm_card_new(struct device *parent, int idx, const char *xid,
 		      struct module *module, size_t extra_size,
@@ -249,6 +251,8 @@ EXPORT_SYMBOL_GPL(snd_devm_card_new);
  * This function handles the explicit snd_card_free() call at the error from
  * the probe callback.  It's just a small helper for simplifying the error
  * handling with the managed devices.
+ *
+ * Return: zero if successful, or a negative error code
  */
 int snd_card_free_on_error(struct device *dev, int ret)
 {
@@ -370,6 +374,8 @@ static int snd_card_init(struct snd_card *card, struct device *parent,
  *
  * Returns a card object corresponding to the given index or NULL if not found.
  * Release the object via snd_card_unref().
+ *
+ * Return: a card object or NULL
  */
 struct snd_card *snd_card_ref(int idx)
 {
@@ -608,6 +614,8 @@ static int snd_card_do_free(struct snd_card *card)
  * resource immediately, but tries to disconnect at first.  When the card
  * is still in use, the function returns before freeing the resources.
  * The card resources will be freed when the refcount gets to zero.
+ *
+ * Return: zero if successful, or a negative error code
  */
 int snd_card_free_when_closed(struct snd_card *card)
 {
@@ -833,6 +841,8 @@ static const struct attribute_group card_dev_attr_group = {
  * snd_card_add_dev_attr - Append a new sysfs attribute group to card
  * @card: card instance
  * @group: attribute group to append
+ *
+ * Return: zero if successful, or a negative error code
  */
 int snd_card_add_dev_attr(struct snd_card *card,
 			  const struct attribute_group *group)
diff --git a/sound/core/isadma.c b/sound/core/isadma.c
index 1f45ede023b4..2602246bd5a0 100644
--- a/sound/core/isadma.c
+++ b/sound/core/isadma.c
@@ -116,8 +116,9 @@ static void __snd_release_dma(struct device *dev, void *data)
  * @dma: the dma number
  * @name: the name string of the requester
  *
- * Returns zero on success, or a negative error code.
  * The requested DMA will be automatically released at unbinding via devres.
+ *
+ * Return: zero on success, or a negative error code
  */
 int snd_devm_request_dma(struct device *dev, int dma, const char *name)
 {
diff --git a/sound/core/vmaster.c b/sound/core/vmaster.c
index ab36f9898711..d0f11f37889b 100644
--- a/sound/core/vmaster.c
+++ b/sound/core/vmaster.c
@@ -494,7 +494,8 @@ EXPORT_SYMBOL_GPL(snd_ctl_sync_vmaster);
  * @arg: optional function argument
  *
  * Apply the function @func to each follower kctl of the given vmaster kctl.
- * Returns 0 if successful, or a negative error code.
+ *
+ * Return: 0 if successful, or a negative error code
  */
 int snd_ctl_apply_vmaster_followers(struct snd_kcontrol *kctl,
 				    int (*func)(struct snd_kcontrol *vfollower,