sound: Clean up docbook warnings
Subsystems (3)
Jonathan Corbet
maintainerPATCH 1/1 sound: Clean up docbook warnings
A number of functions and structures in the sound subsystem had incomplete and/or obsolete DocBook comments, leading to warnings when the docs were built. Correct those comments so that we can enjoy our audio in the absence of warning noise.
---
NOTE that it would be good if somebody more knowledgeable than me checked my work, since I had to fill in a couple of things.
Documentation/DocBook/alsa-driver-api.tmpl | 2 +- include/sound/soc.h | 11 +++++++---- sound/soc/soc-core.c | 17 +++++++++++------ sound/soc/soc-dapm.c | 2 +- 4 files changed, 20 insertions(+), 12 deletions(-)
Documentation/DocBook/alsa-driver-api.tmpl +1 -1
@@ -108,7 +108,7 @@ <sect1><title>ASoC Core API</title> !Iinclude/sound/soc.h !Esound/soc/soc-core.c -!Esound/soc/soc-cache.c +<!-- !Esound/soc/soc-cache.c no docbook comments here --> !Esound/soc/soc-devres.c !Esound/soc/soc-io.c !Esound/soc/soc-pcm.c
include/sound/soc.h +7 -4
@@ -619,6 +619,7 @@ int snd_soc_put_strobe(struct snd_kcontrol *kcontrol,* @pin: name of the pin to update * @mask: bits to check for in reported jack status * @invert: if non-zero then pin is enabled when status is not reported +* @list: internal list entry */ struct snd_soc_jack_pin {struct list_head list;
@@ -635,7 +636,7 @@ struct snd_soc_jack_pin {* @jack_type: type of jack that is expected for this voltage * @debounce_time: debounce_time for jack, codec driver should wait for this * duration before reading the adc for voltages -* @:list: list container +* @list: internal list entry */ struct snd_soc_jack_zone {unsigned int min_mv;
@@ -651,12 +652,12 @@ struct snd_soc_jack_zone {* @gpio: legacy gpio number * @idx: gpio descriptor index within the function of the GPIO * consumer device -* @gpiod_dev GPIO consumer device +* @gpiod_dev: GPIO consumer device * @name: gpio name. Also as connection ID for the GPIO consumer * device function name lookup * @report: value to report when jack detected * @invert: report presence in low state -* @debouce_time: debouce time in ms +* @debounce_time: debounce time in ms * @wake: enable as wake source * @jack_status_check: callback function which overrides the detection * to provide more complex checks (eg, reading an
@@ -672,11 +673,13 @@ struct snd_soc_jack_gpio {int debounce_time;bool wake; +/* private: */ struct snd_soc_jack *jack;struct delayed_work work;struct gpio_desc *desc;void *data; +/* public: */ int (*jack_status_check)(void *data); };
@@ -1319,7 +1322,7 @@ static inline struct snd_soc_dapm_context *snd_soc_codec_get_dapm(/** * snd_soc_dapm_init_bias_level() - Initialize CODEC DAPM bias level -* @dapm: The CODEC for which to initialize the DAPM bias level +* @codec: The CODEC for which to initialize the DAPM bias level * @level: The DAPM level to initialize to * * Initializes the CODEC DAPM bias level. See snd_soc_dapm_init_bias_level().
sound/soc/soc-core.c +11 -6
@@ -2127,7 +2127,7 @@ EXPORT_SYMBOL_GPL(snd_soc_codec_set_pll);/** * snd_soc_dai_set_bclk_ratio - configure BCLK to sample rate ratio. * @dai: DAI -* @ratio Ratio of BCLK to Sample rate. +* @ratio: Ratio of BCLK to Sample rate. * * Configures the DAI for a preset BCLK to sample rate ratio. */
@@ -2798,6 +2798,7 @@ EXPORT_SYMBOL_GPL(snd_soc_register_component);/** * snd_soc_unregister_component - Unregister a component from the ASoC core * +* @dev: The device to unregister */ void snd_soc_unregister_component (struct device *dev) {
@@ -2838,7 +2839,7 @@ static void snd_soc_platform_drv_remove(struct snd_soc_component *component)* snd_soc_add_platform - Add a platform to the ASoC core * @dev: The parent device for the platform * @platform: The platform to add -* @platform_driver: The driver for the platform +* @platform_drv: The driver for the platform */ int snd_soc_add_platform (struct device *dev,struct snd_soc_platform *platform,const struct snd_soc_platform_driver *platform_drv)
@@ -2877,7 +2878,8 @@ EXPORT_SYMBOL_GPL(snd_soc_add_platform);/** * snd_soc_register_platform - Register a platform with the ASoC core * -* @platform: platform to register +* @dev: The device for the platform +* @platform_drv: The driver for the platform */ int snd_soc_register_platform (struct device *dev,const struct snd_soc_platform_driver *platform_drv)
@@ -2938,7 +2940,7 @@ EXPORT_SYMBOL_GPL(snd_soc_lookup_platform);/** * snd_soc_unregister_platform - Unregister a platform from the ASoC core * -* @platform: platform to unregister +* @dev: platform to unregister */ void snd_soc_unregister_platform (struct device *dev) {
@@ -3029,7 +3031,10 @@ static int snd_soc_codec_set_bias_level(struct snd_soc_dapm_context *dapm,/** * snd_soc_register_codec - Register a codec with the ASoC core * -* @codec: codec to register +* @dev: The parent device for this codec +* @codec_drv: Codec driver +* @dai_drv: The associated DAI driver +* @num_dai: Number of DAIs */ int snd_soc_register_codec(struct device *dev, const struct snd_soc_codec_driver *codec_drv,
@@ -3128,7 +3133,7 @@ EXPORT_SYMBOL_GPL(snd_soc_register_codec);/** * snd_soc_unregister_codec - Unregister a codec from the ASoC core * -* @codec: codec to unregister +* @dev: codec to unregister */ void snd_soc_unregister_codec (struct device *dev) {
sound/soc/soc-dapm.c +1 -1
@@ -2911,7 +2911,7 @@ EXPORT_SYMBOL_GPL(snd_soc_dapm_weak_routes);/** * snd_soc_dapm_new_widgets - add new dapm widgets -* @dapm: DAPM context +* @card: card to be checked for new dapm widgets * * Checks the codec for any new dapm widgets and creates them if found. *
Signature · 1 line
2.4.3
Quoted 10 lines · Jonathan Corbet
A number of functions and structures in the sound subsystem had incomplete and/or obsolete DocBook comments, leading to warnings when the docs were built. Correct those comments so that we can enjoy our audio in the absence of warning noise.
Signed-off-by Jonathan Corbet <[email protected]>---
NOTE that it would be good if somebody more knowledgeable than me checked my work, since I had to fill in a couple of things.
All these are ASoC ones... Mark, could you check this?
thanks,
Takashi
Quoted 165 lines
Documentation/DocBook/alsa-driver-api.tmpl | 2 +- include/sound/soc.h | 11 +++++++---- sound/soc/soc-core.c | 17 +++++++++++------ sound/soc/soc-dapm.c | 2 +- 4 files changed, 20 insertions(+), 12 deletions(-)Documentation/DocBook/alsa-driver-api.tmpl +1
-1@@ -108,7 +108,7 @@ <sect1><title>ASoC Core API</title> !Iinclude/sound/soc.h !Esound/soc/soc-core.c -!Esound/soc/soc-cache.c +<!-- !Esound/soc/soc-cache.c no docbook comments here --> !Esound/soc/soc-devres.c !Esound/soc/soc-io.c !Esound/soc/soc-pcm.cinclude/sound/soc.h +7
-4@@ -619,6 +619,7 @@ int snd_soc_put_strobe(struct snd_kcontrol *kcontrol,* @pin: name of the pin to update * @mask: bits to check for in reported jack status * @invert: if non-zero then pin is enabled when status is not reported +* @list: internal list entry */ struct snd_soc_jack_pin {struct list_head list;@@ -635,7 +636,7 @@ struct snd_soc_jack_pin {* @jack_type: type of jack that is expected for this voltage * @debounce_time: debounce_time for jack, codec driver should wait for this * duration before reading the adc for voltages -* @:list: list container +* @list: internal list entry */ struct snd_soc_jack_zone {unsigned int min_mv;@@ -651,12 +652,12 @@ struct snd_soc_jack_zone {* @gpio: legacy gpio number * @idx: gpio descriptor index within the function of the GPIO * consumer device -* @gpiod_dev GPIO consumer device +* @gpiod_dev: GPIO consumer device * @name: gpio name. Also as connection ID for the GPIO consumer * device function name lookup * @report: value to report when jack detected * @invert: report presence in low state -* @debouce_time: debouce time in ms +* @debounce_time: debounce time in ms * @wake: enable as wake source * @jack_status_check: callback function which overrides the detection * to provide more complex checks (eg, reading an @@ -672,11 +673,13 @@ struct snd_soc_jack_gpio {int debounce_time;bool wake; +/* private: */ struct snd_soc_jack *jack;struct delayed_work work;struct gpio_desc *desc;void *data; +/* public: */ int (*jack_status_check)(void *data); };@@ -1319,7 +1322,7 @@ static inline struct snd_soc_dapm_context *snd_soc_codec_get_dapm(/** * snd_soc_dapm_init_bias_level() - Initialize CODEC DAPM bias level -* @dapm: The CODEC for which to initialize the DAPM bias level +* @codec: The CODEC for which to initialize the DAPM bias level * @level: The DAPM level to initialize to * * Initializes the CODEC DAPM bias level. See snd_soc_dapm_init_bias_level(). sound/soc/soc-core.c +11
-6@@ -2127,7 +2127,7 @@ EXPORT_SYMBOL_GPL(snd_soc_codec_set_pll);/** * snd_soc_dai_set_bclk_ratio - configure BCLK to sample rate ratio. * @dai: DAI -* @ratio Ratio of BCLK to Sample rate. +* @ratio: Ratio of BCLK to Sample rate. * * Configures the DAI for a preset BCLK to sample rate ratio. */ @@ -2798,6 +2798,7 @@ EXPORT_SYMBOL_GPL(snd_soc_register_component);/** * snd_soc_unregister_component - Unregister a component from the ASoC core * +* @dev: The device to unregister */ void snd_soc_unregister_component (struct device *dev) {@@ -2838,7 +2839,7 @@ static void snd_soc_platform_drv_remove(struct snd_soc_component *component)* snd_soc_add_platform - Add a platform to the ASoC core * @dev: The parent device for the platform * @platform: The platform to add -* @platform_driver: The driver for the platform +* @platform_drv: The driver for the platform */ int snd_soc_add_platform (struct device *dev,struct snd_soc_platform *platform,const struct snd_soc_platform_driver *platform_drv)@@ -2877,7 +2878,8 @@ EXPORT_SYMBOL_GPL(snd_soc_add_platform);/** * snd_soc_register_platform - Register a platform with the ASoC core * -* @platform: platform to register +* @dev: The device for the platform +* @platform_drv: The driver for the platform */ int snd_soc_register_platform (struct device *dev,const struct snd_soc_platform_driver *platform_drv)@@ -2938,7 +2940,7 @@ EXPORT_SYMBOL_GPL(snd_soc_lookup_platform);/** * snd_soc_unregister_platform - Unregister a platform from the ASoC core * -* @platform: platform to unregister +* @dev: platform to unregister */ void snd_soc_unregister_platform (struct device *dev) {@@ -3029,7 +3031,10 @@ static int snd_soc_codec_set_bias_level(struct snd_soc_dapm_context *dapm,/** * snd_soc_register_codec - Register a codec with the ASoC core * -* @codec: codec to register +* @dev: The parent device for this codec +* @codec_drv: Codec driver +* @dai_drv: The associated DAI driver +* @num_dai: Number of DAIs */ int snd_soc_register_codec(struct device *dev, const struct snd_soc_codec_driver *codec_drv,@@ -3128,7 +3133,7 @@ EXPORT_SYMBOL_GPL(snd_soc_register_codec);/** * snd_soc_unregister_codec - Unregister a codec from the ASoC core * -* @codec: codec to unregister +* @dev: codec to unregister */ void snd_soc_unregister_codec (struct device *dev) {sound/soc/soc-dapm.c +1
-1@@ -2911,7 +2911,7 @@ EXPORT_SYMBOL_GPL(snd_soc_dapm_weak_routes);/** * snd_soc_dapm_new_widgets - add new dapm widgets -* @dapm: DAPM context +* @card: card to be checked for new dapm widgets * * Checks the codec for any new dapm widgets and creates them if found. * Signature · 1 line
2.4.3
Mark Brown
maintainerQuoted 8 lines · Takashi Iwai
Quoted 4 lines · Jonathan Corbet
A number of functions and structures in the sound subsystem had incomplete and/or obsolete DocBook comments, leading to warnings when the docs were built. Correct those comments so that we can enjoy our audio in the absence of warning noise.
Quoted 6 lines
Quoted 4 lines
Signed-off-by Jonathan Corbet <[email protected]>NOTE that it would be good if somebody more knowledgeable than me checked my work, since I had to fill in a couple of things.
All these are ASoC ones... Mark, could you check this?
I don't have a copy of the patch.
Quoted 10 lines · Mark Brown
Quoted 7 lines · Takashi Iwai
Quoted 4 lines · Jonathan Corbet
A number of functions and structures in the sound subsystem had incomplete and/or obsolete DocBook comments, leading to warnings when the docs were built. Correct those comments so that we can enjoy our audio in the absence of warning noise.
Quoted 8 lines
Quoted 6 lines
Quoted 4 lines
Signed-off-by Jonathan Corbet <[email protected]>NOTE that it would be good if somebody more knowledgeable than me checked my work, since I had to fill in a couple of things.
All these are ASoC ones... Mark, could you check this?
I don't have a copy of the patch.
It's on alsa-devel ML.
Takashi
Mark Brown
maintainerQuoted 8 lines · Takashi Iwai
Quoted 5 lines · Mark Brown
Quoted 1 line · Takashi Iwai
All these are ASoC ones... Mark, could you check this?
I don't have a copy of the patch.
It's on alsa-devel ML.
Sure, but as a result of being at Plumbers last week I currently have about 100 patches actually in my inbox that need review and I don't need to go trawling for...
Quoted 7 lines · Mark Brown
Quoted 4 lines · Takashi Iwai
Quoted 3 lines · Mark Brown
Quoted 1 line · Takashi Iwai
All these are ASoC ones... Mark, could you check this?
Quoted 7 lines
Quoted 3 lines
Quoted 1 line
I don't have a copy of the patch.
It's on alsa-devel ML.
Sure, but as a result of being at Plumbers last week I currently have about 100 patches actually in my inbox that need review and I don't need to go trawling for...
If you need the patch in your inbox, I can forward the original post.
Takashi
Mark Brown
maintainerQuoted 5 lines · Takashi Iwai
Quoted 3 lines · Mark Brown
Quoted 1 line · Takashi Iwai
Quoted 1 line
I don't have a copy of the patch.
Quoted 7 lines
Quoted 5 lines
Quoted 1 line
It's on alsa-devel ML.
Sure, but as a result of being at Plumbers last week I currently have about 100 patches actually in my inbox that need review and I don't need to go trawling for...
If you need the patch in your inbox, I can forward the original post.
That was what I was asking for, yes. I see Jon already did that.
Jonathan Corbet
maintainerQuoted 3 lines · On Tue, 25 Aug 2015 07:47:39 +0100 Mark Brown <[email protected]> wrote:
Sure, but as a result of being at Plumbers last week I currently have about 100 patches actually in my inbox that need review and I don't need to go trawling for...
Sorry, should have cc'd you on it from the beginning. Here's a copy...
Thanks,
jon
Quoted 1 line
From
c1efe503d05c1a9a1cb5e0c9c3e39b4e74f2ead2Mon Sep 17 00:00:00 2001
From: Jonathan Corbet <[email protected]>
Date: Sun, 16 Aug 2015 16:56:21 -0600
Subject: [PATCH] sound: Clean up docbook warnings
A number of functions and structures in the sound subsystem had incomplete and/or obsolete DocBook comments, leading to warnings when the docs were built. Correct those comments so that we can enjoy our audio in the absence of warning noise.
--- Documentation/DocBook/alsa-driver-api.tmpl | 2 +- include/sound/soc.h | 11 +++++++---- sound/soc/soc-core.c | 17 +++++++++++------ sound/soc/soc-dapm.c | 2 +- 4 files changed, 20 insertions(+), 12 deletions(-)
Documentation/DocBook/alsa-driver-api.tmpl +1 -1
@@ -108,7 +108,7 @@ <sect1><title>ASoC Core API</title> !Iinclude/sound/soc.h !Esound/soc/soc-core.c -!Esound/soc/soc-cache.c +<!-- !Esound/soc/soc-cache.c no docbook comments here --> !Esound/soc/soc-devres.c !Esound/soc/soc-io.c !Esound/soc/soc-pcm.c
include/sound/soc.h +7 -4
@@ -619,6 +619,7 @@ int snd_soc_put_strobe(struct snd_kcontrol *kcontrol,* @pin: name of the pin to update * @mask: bits to check for in reported jack status * @invert: if non-zero then pin is enabled when status is not reported +* @list: internal list entry */ struct snd_soc_jack_pin {struct list_head list;
@@ -635,7 +636,7 @@ struct snd_soc_jack_pin {* @jack_type: type of jack that is expected for this voltage * @debounce_time: debounce_time for jack, codec driver should wait for this * duration before reading the adc for voltages -* @:list: list container +* @list: internal list entry */ struct snd_soc_jack_zone {unsigned int min_mv;
@@ -651,12 +652,12 @@ struct snd_soc_jack_zone {* @gpio: legacy gpio number * @idx: gpio descriptor index within the function of the GPIO * consumer device -* @gpiod_dev GPIO consumer device +* @gpiod_dev: GPIO consumer device * @name: gpio name. Also as connection ID for the GPIO consumer * device function name lookup * @report: value to report when jack detected * @invert: report presence in low state -* @debouce_time: debouce time in ms +* @debounce_time: debounce time in ms * @wake: enable as wake source * @jack_status_check: callback function which overrides the detection * to provide more complex checks (eg, reading an
@@ -672,11 +673,13 @@ struct snd_soc_jack_gpio {int debounce_time;bool wake; +/* private: */ struct snd_soc_jack *jack;struct delayed_work work;struct gpio_desc *desc;void *data; +/* public: */ int (*jack_status_check)(void *data); };
@@ -1319,7 +1322,7 @@ static inline struct snd_soc_dapm_context *snd_soc_codec_get_dapm(/** * snd_soc_dapm_init_bias_level() - Initialize CODEC DAPM bias level -* @dapm: The CODEC for which to initialize the DAPM bias level +* @codec: The CODEC for which to initialize the DAPM bias level * @level: The DAPM level to initialize to * * Initializes the CODEC DAPM bias level. See snd_soc_dapm_init_bias_level().
sound/soc/soc-core.c +11 -6
@@ -2127,7 +2127,7 @@ EXPORT_SYMBOL_GPL(snd_soc_codec_set_pll);/** * snd_soc_dai_set_bclk_ratio - configure BCLK to sample rate ratio. * @dai: DAI -* @ratio Ratio of BCLK to Sample rate. +* @ratio: Ratio of BCLK to Sample rate. * * Configures the DAI for a preset BCLK to sample rate ratio. */
@@ -2798,6 +2798,7 @@ EXPORT_SYMBOL_GPL(snd_soc_register_component);/** * snd_soc_unregister_component - Unregister a component from the ASoC core * +* @dev: The device to unregister */ void snd_soc_unregister_component (struct device *dev) {
@@ -2838,7 +2839,7 @@ static void snd_soc_platform_drv_remove(struct snd_soc_component *component)* snd_soc_add_platform - Add a platform to the ASoC core * @dev: The parent device for the platform * @platform: The platform to add -* @platform_driver: The driver for the platform +* @platform_drv: The driver for the platform */ int snd_soc_add_platform (struct device *dev,struct snd_soc_platform *platform,const struct snd_soc_platform_driver *platform_drv)
@@ -2877,7 +2878,8 @@ EXPORT_SYMBOL_GPL(snd_soc_add_platform);/** * snd_soc_register_platform - Register a platform with the ASoC core * -* @platform: platform to register +* @dev: The device for the platform +* @platform_drv: The driver for the platform */ int snd_soc_register_platform (struct device *dev,const struct snd_soc_platform_driver *platform_drv)
@@ -2938,7 +2940,7 @@ EXPORT_SYMBOL_GPL(snd_soc_lookup_platform);/** * snd_soc_unregister_platform - Unregister a platform from the ASoC core * -* @platform: platform to unregister +* @dev: platform to unregister */ void snd_soc_unregister_platform (struct device *dev) {
@@ -3029,7 +3031,10 @@ static int snd_soc_codec_set_bias_level(struct snd_soc_dapm_context *dapm,/** * snd_soc_register_codec - Register a codec with the ASoC core * -* @codec: codec to register +* @dev: The parent device for this codec +* @codec_drv: Codec driver +* @dai_drv: The associated DAI driver +* @num_dai: Number of DAIs */ int snd_soc_register_codec(struct device *dev, const struct snd_soc_codec_driver *codec_drv,
@@ -3128,7 +3133,7 @@ EXPORT_SYMBOL_GPL(snd_soc_register_codec);/** * snd_soc_unregister_codec - Unregister a codec from the ASoC core * -* @codec: codec to unregister +* @dev: codec to unregister */ void snd_soc_unregister_codec (struct device *dev) {
sound/soc/soc-dapm.c +1 -1
@@ -2911,7 +2911,7 @@ EXPORT_SYMBOL_GPL(snd_soc_dapm_weak_routes);/** * snd_soc_dapm_new_widgets - add new dapm widgets -* @dapm: DAPM context +* @card: card to be checked for new dapm widgets * * Checks the codec for any new dapm widgets and creates them if found. *
Signature · 1 line
2.4.3
Quoted 9 lines · Jonathan Corbet
Quoted 3 lines · On Tue, 25 Aug 2015 07:47:39 +0100 Mark Brown <[email protected]> wrote:
Sure, but as a result of being at Plumbers last week I currently have about 100 patches actually in my inbox that need review and I don't need to go trawling for...
Sorry, should have cc'd you on it from the beginning. Here's a copy...
Quoted 8 lines
Thanks,
jon
From
c1efe503d05c1a9a1cb5e0c9c3e39b4e74f2ead2Mon Sep 17 00:00:00 2001
From: Jonathan Corbet <[email protected]>
Date: Sun, 16 Aug 2015 16:56:21 -0600
Subject: [PATCH] sound: Clean up docbook warnings
Applied, but please don't bury patches in the middle of a reply in a mail thread - it makes them difficult to apply.