| Message ID | 1415637045-20868-1-git-send-email-tiwai@suse.de (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
On Mon, Nov 10, 2014 at 05:30:45PM +0100, Takashi Iwai wrote:
> + * @list: linked list of assigned pins to the same jack
I thought there was a way to mark implementation details that the user
isn't supposed to look at as such in kerneldoc?
At Mon, 10 Nov 2014 17:55:08 +0000, Mark Brown wrote: > > On Mon, Nov 10, 2014 at 05:30:45PM +0100, Takashi Iwai wrote: > > > + * @list: linked list of assigned pins to the same jack > > I thought there was a way to mark implementation details that the user > isn't supposed to look at as such in kerneldoc? You can put /* private: */ and /* public: */ comments. See Documentation/kernel-doc-nano-HOWTO.txt. But in this case, the list item appears as the first, so it'd become a bit ugly. Also, struct snd_soc_jack_zone has already the description of list item, so having only one shown and one hidden would be inconsistent. For these reasons, I chose to add a comment on it, too. Takashi
On Mon, Nov 10, 2014 at 08:09:45PM +0100, Takashi Iwai wrote: > Mark Brown wrote: > > On Mon, Nov 10, 2014 at 05:30:45PM +0100, Takashi Iwai wrote: > > > + * @list: linked list of assigned pins to the same jack > > I thought there was a way to mark implementation details that the user > > isn't supposed to look at as such in kerneldoc? > You can put /* private: */ and /* public: */ comments. See > Documentation/kernel-doc-nano-HOWTO.txt. > But in this case, the list item appears as the first, so it'd become a > bit ugly. Also, struct snd_soc_jack_zone has already the description > of list item, so having only one shown and one hidden would be > inconsistent. For these reasons, I chose to add a comment on it, > too. If we are going to do this sort of stuff and have people looking at the output I'd prefer that we did do those annotations (and move things around). This just happened to be the first change in the diff but I'd guess there may be some other things that are undocumented because people aren't supposed to be looking at them (as well as ones that were just missed).
At Mon, 10 Nov 2014 19:22:11 +0000, Mark Brown wrote: > > On Mon, Nov 10, 2014 at 08:09:45PM +0100, Takashi Iwai wrote: > > Mark Brown wrote: > > > > On Mon, Nov 10, 2014 at 05:30:45PM +0100, Takashi Iwai wrote: > > > > > + * @list: linked list of assigned pins to the same jack > > > > I thought there was a way to mark implementation details that the user > > > isn't supposed to look at as such in kerneldoc? > > > You can put /* private: */ and /* public: */ comments. See > > Documentation/kernel-doc-nano-HOWTO.txt. > > > But in this case, the list item appears as the first, so it'd become a > > bit ugly. Also, struct snd_soc_jack_zone has already the description > > of list item, so having only one shown and one hidden would be > > inconsistent. For these reasons, I chose to add a comment on it, > > too. > > If we are going to do this sort of stuff and have people looking at the > output I'd prefer that we did do those annotations (and move things > around). This just happened to be the first change in the diff but I'd > guess there may be some other things that are undocumented because > people aren't supposed to be looking at them (as well as ones that were > just missed). I don't mind in which ways. Showing and hiding have both pros and cons. Please just fix your code before I pull for 3.19! Takashi
On Mon, Nov 10, 2014 at 08:26:45PM +0100, Takashi Iwai wrote: > Mark Brown wrote: > > If we are going to do this sort of stuff and have people looking at the > > output I'd prefer that we did do those annotations (and move things > > around). This just happened to be the first change in the diff but I'd > > guess there may be some other things that are undocumented because > > people aren't supposed to be looking at them (as well as ones that were > > just missed). > I don't mind in which ways. Showing and hiding have both pros and > cons. Please just fix your code before I pull for 3.19! Well, I think someone who cares should fix it! :P More seriously it's on the list but I'm having a hard time seeing it as being super urgent - it's more in the nice to have range for me.
At Mon, 10 Nov 2014 19:58:02 +0000, Mark Brown wrote: > > On Mon, Nov 10, 2014 at 08:26:45PM +0100, Takashi Iwai wrote: > > Mark Brown wrote: > > > > If we are going to do this sort of stuff and have people looking at the > > > output I'd prefer that we did do those annotations (and move things > > > around). This just happened to be the first change in the diff but I'd > > > guess there may be some other things that are undocumented because > > > people aren't supposed to be looking at them (as well as ones that were > > > just missed). > > > I don't mind in which ways. Showing and hiding have both pros and > > cons. Please just fix your code before I pull for 3.19! > > Well, I think someone who cares should fix it! :P Heh, *we* agreed on fixing / enhancing documentation in the previous meeting. > More seriously it's on the list but I'm having a hard time seeing it as > being super urgent - it's more in the nice to have range for me. Well, I see this a bit differently. As discussed, we should be really more strict on documentation. From now on, any new API function and struct should mandate kerneldoc comments. At least, I'll watch out in the future pull request and patch reviews. And, fixing these trivial kerneldoc makes things a bit easier; otherwise the new warnings will be buried in other old warnings. In anyway, I'll send a v2 patch soon later. Takashi
On Mon, Nov 10, 2014 at 09:45:26PM +0100, Takashi Iwai wrote: > Mark Brown wrote: > > > I don't mind in which ways. Showing and hiding have both pros and > > > cons. Please just fix your code before I pull for 3.19! > > Well, I think someone who cares should fix it! :P > Heh, *we* agreed on fixing / enhancing documentation in the previous > meeting. I totally agree that someone should do that work :) > > More seriously it's on the list but I'm having a hard time seeing it as > > being super urgent - it's more in the nice to have range for me. > Well, I see this a bit differently. As discussed, we should be really > more strict on documentation. From now on, any new API function and > struct should mandate kerneldoc comments. At least, I'll watch out in > the future pull request and patch reviews. And, fixing these trivial > kerneldoc makes things a bit easier; otherwise the new warnings will > be buried in other old warnings. Right, and I am enforcing that for new stuff. Since we don't currently generate linuxdoc outputs we don't currently get any warnings and I'm not seeing much demand for the actual outputs (as opposed to the comments in the code which are useful; AFAICT that's the way most people consume linuxdoc).
At Tue, 11 Nov 2014 00:32:05 +0000, Mark Brown wrote: > > On Mon, Nov 10, 2014 at 09:45:26PM +0100, Takashi Iwai wrote: > > Mark Brown wrote: > > > > > I don't mind in which ways. Showing and hiding have both pros and > > > > cons. Please just fix your code before I pull for 3.19! > > > > Well, I think someone who cares should fix it! :P > > > Heh, *we* agreed on fixing / enhancing documentation in the previous > > meeting. > > I totally agree that someone should do that work :) > > > > More seriously it's on the list but I'm having a hard time seeing it as > > > being super urgent - it's more in the nice to have range for me. > > > Well, I see this a bit differently. As discussed, we should be really > > more strict on documentation. From now on, any new API function and > > struct should mandate kerneldoc comments. At least, I'll watch out in > > the future pull request and patch reviews. And, fixing these trivial > > kerneldoc makes things a bit easier; otherwise the new warnings will > > be buried in other old warnings. > > Right, and I am enforcing that for new stuff. Since we don't currently > generate linuxdoc outputs we don't currently get any warnings and I'm > not seeing much demand for the actual outputs (as opposed to the > comments in the code which are useful; AFAICT that's the way most people > consume linuxdoc). We do generate linuxdoc outputs for 3.19 :) That's why I've been working on fixing the issues. Takashi
diff --git a/include/sound/soc.h b/include/sound/soc.h index 7ba7130037a0..25d0bdbbeb11 100644 --- a/include/sound/soc.h +++ b/include/sound/soc.h @@ -583,6 +583,7 @@ int snd_soc_put_strobe(struct snd_kcontrol *kcontrol, /** * struct snd_soc_jack_pin - Describes a pin to update based on jack detection * + * @list: linked list of assigned pins to the same jack * @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 @@ -602,7 +603,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: list container */ struct snd_soc_jack_zone { unsigned int min_mv; @@ -618,16 +619,20 @@ 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: debouce time in ms * @wake: enable as wake source + * @jack: assigned jack + * @work: delayed_work for GPIO detection + * @desc: GPIO descriptor * @jack_status_check: callback function which overrides the detection * to provide more complex checks (eg, reading an * ADC). + * @data: arbitrary data passed to jack_status_check callback */ struct snd_soc_jack_gpio { unsigned int gpio; diff --git a/sound/soc/soc-core.c b/sound/soc/soc-core.c index 4c8f8a23a0e9..74a8a80e2d9a 100644 --- a/sound/soc/soc-core.c +++ b/sound/soc/soc-core.c @@ -2113,6 +2113,8 @@ EXPORT_SYMBOL_GPL(snd_soc_set_ac97_ops); /** * snd_soc_set_ac97_ops_of_reset - Set ac97 ops with generic ac97 reset functions + * @ops: AC97 opts to set + * @pdev: platform to deal with * * This function sets the reset and warm_reset properties of ops and parses * the device node of pdev to get pinctrl states and gpio numbers to use. @@ -2685,7 +2687,7 @@ EXPORT_SYMBOL_GPL(snd_soc_get_volsw_sx); /** * snd_soc_put_volsw_sx - double mixer set callback * @kcontrol: mixer control - * @uinfo: control element information + * @ucontrol: control element information * * Callback to set the value of a double mixer control that spans 2 registers. * @@ -3458,7 +3460,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. */ @@ -4082,6 +4084,7 @@ EXPORT_SYMBOL_GPL(snd_soc_register_component); /** * snd_soc_unregister_component - Unregister a component from the ASoC core + * @dev: device to unregister * */ void snd_soc_unregister_component(struct device *dev) @@ -4119,7 +4122,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) @@ -4158,7 +4161,8 @@ EXPORT_SYMBOL_GPL(snd_soc_add_platform); /** * snd_soc_register_platform - Register a platform with the ASoC core * - * @platform: platform to register + * @dev: platform to register + * @platform_drv: the driver for the platform */ int snd_soc_register_platform(struct device *dev, const struct snd_soc_platform_driver *platform_drv) @@ -4215,7 +4219,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) { @@ -4306,7 +4310,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: codec to register + * @codec_drv: the codec driver to register + * @dai_drv: the array of DAI drivers to register + * @num_dai: the number of DAIs to register */ int snd_soc_register_codec(struct device *dev, const struct snd_soc_codec_driver *codec_drv, @@ -4406,7 +4413,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) { diff --git a/sound/soc/soc-dapm.c b/sound/soc/soc-dapm.c index c61cb9cedbcd..7050ec1d5b72 100644 --- a/sound/soc/soc-dapm.c +++ b/sound/soc/soc-dapm.c @@ -2680,7 +2680,7 @@ EXPORT_SYMBOL_GPL(snd_soc_dapm_weak_routes); /** * snd_soc_dapm_new_widgets - add new dapm widgets - * @dapm: DAPM context + * @card: card object containing widgets * * Checks the codec for any new dapm widgets and creates them if found. * diff --git a/sound/soc/soc-devres.c b/sound/soc/soc-devres.c index 057e5ef7dcce..a57921eeee81 100644 --- a/sound/soc/soc-devres.c +++ b/sound/soc/soc-devres.c @@ -60,7 +60,7 @@ static void devm_platform_release(struct device *dev, void *res) /** * devm_snd_soc_register_platform - resource managed platform registration * @dev: Device used to manage platform - * @platform: platform to register + * @platform_drv: platform to register * * Register a platform driver with automatic unregistration when the device is * unregistered. diff --git a/sound/soc/soc-jack.c b/sound/soc/soc-jack.c index ab47fea997a3..ef1d42d7c6f6 100644 --- a/sound/soc/soc-jack.c +++ b/sound/soc/soc-jack.c @@ -116,7 +116,7 @@ EXPORT_SYMBOL_GPL(snd_soc_jack_report); * * @jack: ASoC jack * @count: Number of zones - * @zone: Array of zones + * @zones: Array of zones * * After this function has been called the zones specified in the * array will be associated with the jack.
Lots of typos and missing parameter descriptions. Signed-off-by: Takashi Iwai <tiwai@suse.de> --- include/sound/soc.h | 11 ++++++++--- sound/soc/soc-core.c | 21 ++++++++++++++------- sound/soc/soc-dapm.c | 2 +- sound/soc/soc-devres.c | 2 +- sound/soc/soc-jack.c | 2 +- 5 files changed, 25 insertions(+), 13 deletions(-)