diff mbox series

[v2] USB: core: Fix docs warning caused by wireless_status feature

Message ID 20230405092754.36579-1-hadess@hadess.net (mailing list archive)
State New, archived
Headers show
Series [v2] USB: core: Fix docs warning caused by wireless_status feature | expand

Commit Message

Bastien Nocera April 5, 2023, 9:27 a.m. UTC
Fix wrongly named 'dev' parameter in doc block, should have been iface:
drivers/usb/core/message.c:1939: warning: Function parameter or member 'iface' not described in 'usb_set_wireless_status'
drivers/usb/core/message.c:1939: warning: Excess function parameter 'dev' description in 'usb_set_wireless_status'

And fix missing struct member doc in kernel API, and reorder to
match struct:
include/linux/usb.h:270: warning: Function parameter or member 'wireless_status_work' not described in 'usb_interface'

Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
Link: https://lore.kernel.org/linux-next/20230405114807.5a57bf46@canb.auug.org.au/T/#t
Fixes: 0a4db185f078 ("USB: core: Add API to change the wireless_status")
Signed-off-by: Bastien Nocera <hadess@hadess.net>
---
Added missing link and sob, thanks to bentiss for the quick review

 drivers/usb/core/message.c | 2 +-
 include/linux/usb.h        | 6 ++++--
 2 files changed, 5 insertions(+), 3 deletions(-)

Comments

Greg KH April 5, 2023, 5:13 p.m. UTC | #1
On Wed, Apr 05, 2023 at 11:27:54AM +0200, Bastien Nocera wrote:
> Fix wrongly named 'dev' parameter in doc block, should have been iface:
> drivers/usb/core/message.c:1939: warning: Function parameter or member 'iface' not described in 'usb_set_wireless_status'
> drivers/usb/core/message.c:1939: warning: Excess function parameter 'dev' description in 'usb_set_wireless_status'
> 
> And fix missing struct member doc in kernel API, and reorder to
> match struct:
> include/linux/usb.h:270: warning: Function parameter or member 'wireless_status_work' not described in 'usb_interface'
> 
> Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
> Link: https://lore.kernel.org/linux-next/20230405114807.5a57bf46@canb.auug.org.au/T/#t
> Fixes: 0a4db185f078 ("USB: core: Add API to change the wireless_status")

I do not see that git commit id anywhere, where is it from?  What tree?

Ah, input tree, not much I can do there...

thanks,

greg k-h
Bastien Nocera April 5, 2023, 6:03 p.m. UTC | #2
On Wed, 2023-04-05 at 19:13 +0200, Greg Kroah-Hartman wrote:
> On Wed, Apr 05, 2023 at 11:27:54AM +0200, Bastien Nocera wrote:
> > Fix wrongly named 'dev' parameter in doc block, should have been
> > iface:
> > drivers/usb/core/message.c:1939: warning: Function parameter or
> > member 'iface' not described in 'usb_set_wireless_status'
> > drivers/usb/core/message.c:1939: warning: Excess function parameter
> > 'dev' description in 'usb_set_wireless_status'
> > 
> > And fix missing struct member doc in kernel API, and reorder to
> > match struct:
> > include/linux/usb.h:270: warning: Function parameter or member
> > 'wireless_status_work' not described in 'usb_interface'
> > 
> > Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
> > Link:
> > https://lore.kernel.org/linux-next/20230405114807.5a57bf46@canb.auug.org.au/T/#t
> > Fixes: 0a4db185f078 ("USB: core: Add API to change the
> > wireless_status")
> 
> I do not see that git commit id anywhere, where is it from?  What
> tree?
> 
> Ah, input tree, not much I can do there...

Yes, it's from the hid tree.

Benjamin is waiting on either Alan or yourself ack'ing the changes
before pushing it through the hid tree, to avoid stepping on somebody
else's toes.

The patch seems to fix the warnings in my local tests, let me know if
you have any comments about the wording.

Cheers
Greg KH April 5, 2023, 6:06 p.m. UTC | #3
On Wed, Apr 05, 2023 at 08:03:16PM +0200, Bastien Nocera wrote:
> On Wed, 2023-04-05 at 19:13 +0200, Greg Kroah-Hartman wrote:
> > On Wed, Apr 05, 2023 at 11:27:54AM +0200, Bastien Nocera wrote:
> > > Fix wrongly named 'dev' parameter in doc block, should have been
> > > iface:
> > > drivers/usb/core/message.c:1939: warning: Function parameter or
> > > member 'iface' not described in 'usb_set_wireless_status'
> > > drivers/usb/core/message.c:1939: warning: Excess function parameter
> > > 'dev' description in 'usb_set_wireless_status'
> > > 
> > > And fix missing struct member doc in kernel API, and reorder to
> > > match struct:
> > > include/linux/usb.h:270: warning: Function parameter or member
> > > 'wireless_status_work' not described in 'usb_interface'
> > > 
> > > Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
> > > Link:
> > > https://lore.kernel.org/linux-next/20230405114807.5a57bf46@canb.auug.org.au/T/#t
> > > Fixes: 0a4db185f078 ("USB: core: Add API to change the
> > > wireless_status")
> > 
> > I do not see that git commit id anywhere, where is it from?  What
> > tree?
> > 
> > Ah, input tree, not much I can do there...
> 
> Yes, it's from the hid tree.
> 
> Benjamin is waiting on either Alan or yourself ack'ing the changes
> before pushing it through the hid tree, to avoid stepping on somebody
> else's toes.
> 
> The patch seems to fix the warnings in my local tests, let me know if
> you have any comments about the wording.

Nope:

Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Benjamin Tissoires April 6, 2023, 3:15 p.m. UTC | #4
On Wed, 05 Apr 2023 11:27:54 +0200, Bastien Nocera wrote:
> Fix wrongly named 'dev' parameter in doc block, should have been iface:
> drivers/usb/core/message.c:1939: warning: Function parameter or member 'iface' not described in 'usb_set_wireless_status'
> drivers/usb/core/message.c:1939: warning: Excess function parameter 'dev' description in 'usb_set_wireless_status'
> 
> And fix missing struct member doc in kernel API, and reorder to
> match struct:
> include/linux/usb.h:270: warning: Function parameter or member 'wireless_status_work' not described in 'usb_interface'
> 
> [...]

Applied to https://git.kernel.org/pub/scm/linux/kernel/git/hid/hid.git (for-6.4/logitech-hidpp), thanks!

[1/1] USB: core: Fix docs warning caused by wireless_status feature
      https://git.kernel.org/hid/hid/c/539adfedbd2d

Cheers,
Benjamin Tissoires April 6, 2023, 3:17 p.m. UTC | #5
On Wed, Apr 5, 2023 at 8:06 PM Greg Kroah-Hartman
<gregkh@linuxfoundation.org> wrote:
>
> On Wed, Apr 05, 2023 at 08:03:16PM +0200, Bastien Nocera wrote:
> > On Wed, 2023-04-05 at 19:13 +0200, Greg Kroah-Hartman wrote:
> > > On Wed, Apr 05, 2023 at 11:27:54AM +0200, Bastien Nocera wrote:
> > > > Fix wrongly named 'dev' parameter in doc block, should have been
> > > > iface:
> > > > drivers/usb/core/message.c:1939: warning: Function parameter or
> > > > member 'iface' not described in 'usb_set_wireless_status'
> > > > drivers/usb/core/message.c:1939: warning: Excess function parameter
> > > > 'dev' description in 'usb_set_wireless_status'
> > > >
> > > > And fix missing struct member doc in kernel API, and reorder to
> > > > match struct:
> > > > include/linux/usb.h:270: warning: Function parameter or member
> > > > 'wireless_status_work' not described in 'usb_interface'
> > > >
> > > > Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
> > > > Link:
> > > > https://lore.kernel.org/linux-next/20230405114807.5a57bf46@canb.auug.org.au/T/#t
> > > > Fixes: 0a4db185f078 ("USB: core: Add API to change the
> > > > wireless_status")
> > >
> > > I do not see that git commit id anywhere, where is it from?  What
> > > tree?
> > >
> > > Ah, input tree, not much I can do there...
> >
> > Yes, it's from the hid tree.
> >
> > Benjamin is waiting on either Alan or yourself ack'ing the changes
> > before pushing it through the hid tree, to avoid stepping on somebody
> > else's toes.
> >
> > The patch seems to fix the warnings in my local tests, let me know if
> > you have any comments about the wording.
>
> Nope:
>
> Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
>

Thanks!

I have fixed a small checkpatch warning about using space before tab
and applied as the b4 thank you notice should have already mentioned.

Cheers,
Benjamin
diff mbox series

Patch

diff --git a/drivers/usb/core/message.c b/drivers/usb/core/message.c
index 7930dca84616..7c7f88ca4f62 100644
--- a/drivers/usb/core/message.c
+++ b/drivers/usb/core/message.c
@@ -1926,7 +1926,7 @@  static void __usb_wireless_status_intf(struct work_struct *ws)
 
 /**
  * usb_set_wireless_status - sets the wireless_status struct member
- * @dev: the device to modify
+ * @iface: the interface to modify
  * @status: the new wireless status
  *
  * Set the wireless_status struct member to the new value, and emit
diff --git a/include/linux/usb.h b/include/linux/usb.h
index a48eeec62a66..56f4758f3c31 100644
--- a/include/linux/usb.h
+++ b/include/linux/usb.h
@@ -203,14 +203,16 @@  enum usb_wireless_status {
  *	following a reset or suspend operation it doesn't support.
  * @authorized: This allows to (de)authorize individual interfaces instead
  *	a whole device in contrast to the device authorization.
+ * @wireless_status: if the USB device uses a receiver/emitter combo, whether
+ *	the emitter is connected.
+ * @wireless_status_work: Used for scheduling wireless status changes
+ * 	from atomic context.
  * @dev: driver model's view of this device
  * @usb_dev: if an interface is bound to the USB major, this will point
  *	to the sysfs representation for that device.
  * @reset_ws: Used for scheduling resets from atomic context.
  * @resetting_device: USB core reset the device, so use alt setting 0 as
  *	current; needs bandwidth alloc after reset.
- * @wireless_status: if the USB device uses a receiver/emitter combo, whether
- *	the emitter is connected.
  *
  * USB device drivers attach to interfaces on a physical device.  Each
  * interface encapsulates a single high level function, such as feeding