[PATCH v1 1/1] usb: fotg210: Add missing kernel doc description

[PATCH v1 1/1] usb: fotg210: Add missing kernel doc description

[Andy Shevchenko]

kernel-doc validator is not happy:

  warning: Function parameter or struct member 'fotg' not described in 'fotg210_vbus'

Add missing description.

Fixes: 3e679bde529e ("usb: fotg210-udc: Implement VBUS session")
Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
---
 drivers/usb/fotg210/fotg210-core.c | 1 +
 1 file changed, 1 insertion(+)

diff --git a/drivers/usb/fotg210/fotg210-core.c b/drivers/usb/fotg210/fotg210-core.c
index 958fc40eae86..00483da40f04 100644
--- a/drivers/usb/fotg210/fotg210-core.c
+++ b/drivers/usb/fotg210/fotg210-core.c
@@ -95,6 +95,7 @@ static int fotg210_gemini_init(struct fotg210 *fotg, struct resource *res,
 
 /**
  * fotg210_vbus() - Called by gadget driver to enable/disable VBUS
+ * @fotg210: pointer to a private fotg210 object
  * @enable: true to enable VBUS, false to disable VBUS
  */
 void fotg210_vbus(struct fotg210 *fotg, bool enable)
-- 
2.43.0.rc1.1336.g36b5255a03ac

Re: [PATCH v1 1/1] usb: fotg210: Add missing kernel doc description

[kernel test robot]

Hi Andy,

kernel test robot noticed the following build warnings:

[auto build test WARNING on usb/usb-testing]
[also build test WARNING on usb/usb-next usb/usb-linus westeri-thunderbolt/next linus/master v6.9-rc7 next-20240509]
[If your patch is applied to the wrong git tree, kindly drop us a note.
And when submitting patch, we suggest to use '--base' as documented in
https://git-scm.com/docs/git-format-patch#_base_tree_information]

url:    https://github.com/intel-lab-lkp/linux/commits/Andy-Shevchenko/usb-fotg210-Add-missing-kernel-doc-description/20240508-230440
base:   https://git.kernel.org/pub/scm/linux/kernel/git/gregkh/usb.git usb-testing
patch link:    https://lore.kernel.org/r/20240508150335.1378629-1-andriy.shevchenko%40linux.intel.com
patch subject: [PATCH v1 1/1] usb: fotg210: Add missing kernel doc description
config: arc-randconfig-001-20240509 (https://download.01.org/0day-ci/archive/20240509/202405092220.8mfNBVyo-lkp@intel.com/config)
compiler: arceb-elf-gcc (GCC) 13.2.0
reproduce (this is a W=1 build): (https://download.01.org/0day-ci/archive/20240509/202405092220.8mfNBVyo-lkp@intel.com/reproduce)

If you fix the issue in a separate patch/commit (i.e. not just a new version of
the same patch/commit), kindly add following tags
| Reported-by: kernel test robot <lkp@intel.com>
| Closes: https://lore.kernel.org/oe-kbuild-all/202405092220.8mfNBVyo-lkp@intel.com/

All warnings (new ones prefixed by >>):

   drivers/usb/fotg210/fotg210-core.c:102: warning: Function parameter or struct member 'fotg' not described in 'fotg210_vbus'
>> drivers/usb/fotg210/fotg210-core.c:102: warning: Excess function parameter 'fotg210' description in 'fotg210_vbus'


vim +102 drivers/usb/fotg210/fotg210-core.c

00fb05ff87bc63 Linus Walleij   2022-11-09   95  
3e679bde529e89 Linus Walleij   2023-01-18   96  /**
3e679bde529e89 Linus Walleij   2023-01-18   97   * fotg210_vbus() - Called by gadget driver to enable/disable VBUS
16544cb7676b90 Andy Shevchenko 2024-05-08   98   * @fotg210: pointer to a private fotg210 object
3e679bde529e89 Linus Walleij   2023-01-18   99   * @enable: true to enable VBUS, false to disable VBUS
3e679bde529e89 Linus Walleij   2023-01-18  100   */
3e679bde529e89 Linus Walleij   2023-01-18  101  void fotg210_vbus(struct fotg210 *fotg, bool enable)
3e679bde529e89 Linus Walleij   2023-01-18 @102  {
3e679bde529e89 Linus Walleij   2023-01-18  103  	u32 mask;
3e679bde529e89 Linus Walleij   2023-01-18  104  	u32 val;
3e679bde529e89 Linus Walleij   2023-01-18  105  	int ret;
3e679bde529e89 Linus Walleij   2023-01-18  106  
3e679bde529e89 Linus Walleij   2023-01-18  107  	switch (fotg->port) {
3e679bde529e89 Linus Walleij   2023-01-18  108  	case GEMINI_PORT_0:
3e679bde529e89 Linus Walleij   2023-01-18  109  		mask = GEMINI_MISC_USB0_VBUS_ON;
3e679bde529e89 Linus Walleij   2023-01-18  110  		val = enable ? GEMINI_MISC_USB0_VBUS_ON : 0;
3e679bde529e89 Linus Walleij   2023-01-18  111  		break;
3e679bde529e89 Linus Walleij   2023-01-18  112  	case GEMINI_PORT_1:
3e679bde529e89 Linus Walleij   2023-01-18  113  		mask = GEMINI_MISC_USB1_VBUS_ON;
3e679bde529e89 Linus Walleij   2023-01-18  114  		val = enable ? GEMINI_MISC_USB1_VBUS_ON : 0;
3e679bde529e89 Linus Walleij   2023-01-18  115  		break;
3e679bde529e89 Linus Walleij   2023-01-18  116  	default:
3e679bde529e89 Linus Walleij   2023-01-18  117  		return;
3e679bde529e89 Linus Walleij   2023-01-18  118  	}
3e679bde529e89 Linus Walleij   2023-01-18  119  	ret = regmap_update_bits(fotg->map, GEMINI_GLOBAL_MISC_CTRL, mask, val);
3e679bde529e89 Linus Walleij   2023-01-18  120  	if (ret)
3e679bde529e89 Linus Walleij   2023-01-18  121  		dev_err(fotg->dev, "failed to %s VBUS\n",
3e679bde529e89 Linus Walleij   2023-01-18  122  			enable ? "enable" : "disable");
3e679bde529e89 Linus Walleij   2023-01-18  123  	dev_info(fotg->dev, "%s: %s VBUS\n", __func__, enable ? "enable" : "disable");
3e679bde529e89 Linus Walleij   2023-01-18  124  }
3e679bde529e89 Linus Walleij   2023-01-18  125  

-- 
0-DAY CI Kernel Test Service
https://github.com/intel/lkp-tests/wiki

Re: [PATCH v1 1/1] usb: fotg210: Add missing kernel doc description

[Greg Kroah-Hartman]

On Wed, May 08, 2024 at 06:03:35PM +0300, Andy Shevchenko wrote:
> kernel-doc validator is not happy:
> 
>   warning: Function parameter or struct member 'fotg' not described in 'fotg210_vbus'
> 
> Add missing description.
> 
> Fixes: 3e679bde529e ("usb: fotg210-udc: Implement VBUS session")
> Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
> ---
>  drivers/usb/fotg210/fotg210-core.c | 1 +
>  1 file changed, 1 insertion(+)
> 
> diff --git a/drivers/usb/fotg210/fotg210-core.c b/drivers/usb/fotg210/fotg210-core.c
> index 958fc40eae86..00483da40f04 100644
> --- a/drivers/usb/fotg210/fotg210-core.c
> +++ b/drivers/usb/fotg210/fotg210-core.c
> @@ -95,6 +95,7 @@ static int fotg210_gemini_init(struct fotg210 *fotg, struct resource *res,
>  
>  /**
>   * fotg210_vbus() - Called by gadget driver to enable/disable VBUS
> + * @fotg210: pointer to a private fotg210 object
>   * @enable: true to enable VBUS, false to disable VBUS
>   */
>  void fotg210_vbus(struct fotg210 *fotg, bool enable)

I don't think you actually built the documentation after this patch :(

Re: [PATCH v1 1/1] usb: fotg210: Add missing kernel doc description

[Andy Shevchenko]

On Fri, May 10, 2024 at 10:34:05AM +0100, Greg Kroah-Hartman wrote:
> On Wed, May 08, 2024 at 06:03:35PM +0300, Andy Shevchenko wrote:
> > kernel-doc validator is not happy:
> > 
> >   warning: Function parameter or struct member 'fotg' not described in 'fotg210_vbus'
> > 
> > Add missing description.

...

> >  /**
> >   * fotg210_vbus() - Called by gadget driver to enable/disable VBUS
> > + * @fotg210: pointer to a private fotg210 object
> >   * @enable: true to enable VBUS, false to disable VBUS
> >   */
> >  void fotg210_vbus(struct fotg210 *fotg, bool enable)
> 
> I don't think you actually built the documentation after this patch :(

Yeah, it slips over my fingers, sorry. I will try again.

-- 
With Best Regards,
Andy Shevchenko