Re: [PATCH] USB: ohci: ohci_pdriver.h: fix missing kernel-doc comments

[Alan Stern]

On Sat, Feb 28, 2026 at 11:20:12AM -0800, Randy Dunlap wrote:
> Convert comments to kernel-doc format to avoid kernel-doc warnings:
> 
> Warning: include/linux/usb/ohci_pdriver.h:32 struct member 'power_on'
>  not described in 'usb_ohci_pdata'
> Warning: include/linux/usb/ohci_pdriver.h:32 struct member 'power_off'
>  not described in 'usb_ohci_pdata'
> Warning: include/linux/usb/ohci_pdriver.h:32 struct member 'power_suspend'
>  not described in 'usb_ohci_pdata'
> 
> Signed-off-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>
> ---
> Cc: Alan Stern <stern@xxxxxxxxxxxxxxxxxxx>
> Cc: linux-usb@xxxxxxxxxxxxxxx
> Cc: Greg Kroah-Hartman <gregkh@xxxxxxxxxxxxxxxxxxx>
> 
>  include/linux/usb/ohci_pdriver.h |   10 ++++++----
>  1 file changed, 6 insertions(+), 4 deletions(-)
> 
> --- linux-next-20260205.orig/include/linux/usb/ohci_pdriver.h
> +++ linux-next-20260205/include/linux/usb/ohci_pdriver.h
> @@ -23,12 +23,14 @@ struct usb_ohci_pdata {
>  	unsigned	no_big_frame_no:1;
>  	unsigned int	num_ports;
>  
> -	/* Turn on all power and clocks */
> +	/** @power_on: Turn on all power and clocks */
>  	int (*power_on)(struct platform_device *pdev);
> -	/* Turn off all power and clocks */
> +	/** @power_off: Turn off all power and clocks */
>  	void (*power_off)(struct platform_device *pdev);
> -	/* Turn on only VBUS suspend power and hotplug detection,
> -	 * turn off everything else */
> +	/**
> +	 * @power_suspend: Turn on only VBUS suspend power and hotplug
> +	 * detection, turn off everything else
> +	 */
>  	void (*power_suspend)(struct platform_device *pdev);
>  };

Shouldn't the function-pointer descriptions go in the big kerneldoc 
comment just before the start of the structure declaration?  That way 
they would be consistent with the descriptions of the other data fields.

Alan Stern