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

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

[Randy Dunlap]

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@infradead.org>
---
v2: move all kernel-doc comments to before the struct instead of
    having them inline insidet the struct. (Alan)

Cc: Alan Stern <stern@rowland.harvard.edu>
Cc: linux-usb@vger.kernel.org
Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>

 include/linux/usb/ohci_pdriver.h |    8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

--- linux-next-20261102.orig/include/linux/usb/ohci_pdriver.h
+++ linux-next-20261102/include/linux/usb/ohci_pdriver.h
@@ -13,6 +13,10 @@
  * @big_endian_mmio:	BE registers
  * @no_big_frame_no:	no big endian frame_no shift
  * @num_ports:		number of ports
+ * @power_on: Turn on all power and clocks
+ * @power_off: Turn off all power and clocks
+ * @power_suspend: Turn on only VBUS suspend power and hotplug
+ *                 detection, turn off everything else
  *
  * These are general configuration options for the OHCI controller. All of
  * these options are activating more or less workarounds for some hardware.
@@ -23,12 +27,8 @@ struct usb_ohci_pdata {
 	unsigned	no_big_frame_no:1;
 	unsigned int	num_ports;
 
-	/* Turn on all power and clocks */
 	int (*power_on)(struct platform_device *pdev);
-	/* 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 */
 	void (*power_suspend)(struct platform_device *pdev);
 };
 

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

[Alan Stern]

On Mon, Nov 02, 2026 at 05:47:10PM -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@infradead.org>
> ---
> v2: move all kernel-doc comments to before the struct instead of
>     having them inline insidet the struct. (Alan)
> 
> Cc: Alan Stern <stern@rowland.harvard.edu>
> Cc: linux-usb@vger.kernel.org
> Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
> 
>  include/linux/usb/ohci_pdriver.h |    8 ++++----
>  1 file changed, 4 insertions(+), 4 deletions(-)
> 
> --- linux-next-20261102.orig/include/linux/usb/ohci_pdriver.h
> +++ linux-next-20261102/include/linux/usb/ohci_pdriver.h
> @@ -13,6 +13,10 @@
>   * @big_endian_mmio:	BE registers
>   * @no_big_frame_no:	no big endian frame_no shift
>   * @num_ports:		number of ports
> + * @power_on: Turn on all power and clocks
> + * @power_off: Turn off all power and clocks
> + * @power_suspend: Turn on only VBUS suspend power and hotplug
> + *                 detection, turn off everything else

It would be nice if the indentation for these new entries matched the 
indentation for the ones above (1 or 2 tabs instead of 1 space).  Aside 
from that:

Acked-by: Alan Stern <stern@rowland.harvard.edu>

Alan Stern

>   *
>   * These are general configuration options for the OHCI controller. All of
>   * these options are activating more or less workarounds for some hardware.
> @@ -23,12 +27,8 @@ struct usb_ohci_pdata {
>  	unsigned	no_big_frame_no:1;
>  	unsigned int	num_ports;
>  
> -	/* Turn on all power and clocks */
>  	int (*power_on)(struct platform_device *pdev);
> -	/* 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 */
>  	void (*power_suspend)(struct platform_device *pdev);
>  };
>  

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

[Randy Dunlap]

On 11/2/26 7:49 PM, Alan Stern wrote:
> On Mon, Nov 02, 2026 at 05:47:10PM -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@infradead.org>
>> ---
>> v2: move all kernel-doc comments to before the struct instead of
>>     having them inline insidet the struct. (Alan)
>>
>> Cc: Alan Stern <stern@rowland.harvard.edu>
>> Cc: linux-usb@vger.kernel.org
>> Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
>>
>>  include/linux/usb/ohci_pdriver.h |    8 ++++----
>>  1 file changed, 4 insertions(+), 4 deletions(-)
>>
>> --- linux-next-20261102.orig/include/linux/usb/ohci_pdriver.h
>> +++ linux-next-20261102/include/linux/usb/ohci_pdriver.h
>> @@ -13,6 +13,10 @@
>>   * @big_endian_mmio:	BE registers
>>   * @no_big_frame_no:	no big endian frame_no shift
>>   * @num_ports:		number of ports
>> + * @power_on: Turn on all power and clocks
>> + * @power_off: Turn off all power and clocks
>> + * @power_suspend: Turn on only VBUS suspend power and hotplug
>> + *                 detection, turn off everything else
> 
> It would be nice if the indentation for these new entries matched the 
> indentation for the ones above (1 or 2 tabs instead of 1 space).  Aside 
> from that:
> 
> Acked-by: Alan Stern <stern@rowland.harvard.edu>
> 

Agreed. I'll send a v3.
Thanks.

> 
>>   *
>>   * These are general configuration options for the OHCI controller. All of
>>   * these options are activating more or less workarounds for some hardware.
>> @@ -23,12 +27,8 @@ struct usb_ohci_pdata {
>>  	unsigned	no_big_frame_no:1;
>>  	unsigned int	num_ports;
>>  
>> -	/* Turn on all power and clocks */
>>  	int (*power_on)(struct platform_device *pdev);
>> -	/* 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 */
>>  	void (*power_suspend)(struct platform_device *pdev);
>>  };
>>  

-- 
~Randy