USB: fix up movement of USB core kerneldoc location

Commit 855b35ea96c4 ("usb: common: move function's kerneldoc next to its definition") moved the USB common function documentation out of the .h file and into the .c file. But, we forgot to tell the Documentation where the new information is at, resulting in a build warning of:
include/linux/usb/ch9.h:1: warning: no structured comments found

Fix that up by pointing the documentation at the correct location.

Fixes 855b35ea96c4 ("usb: common: move function's kerneldoc next to its definition")

Cc Chunfeng Yun <[email protected]>

Cc Alan Stern <[email protected]>

Reported-by Stephen Rothwell <[email protected]>

Signed-off-by Greg Kroah-Hartman <[email protected]>

---
 Documentation/driver-api/usb/usb.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

Documentation/driver-api/usb/usb.rst +1 -1

index 078e981e2b16..c08b92558dcb 100644
@@ -114,7 +114,7 @@ chapter 9 of the USB specification. These data types are used throughout
 USB, and in APIs including this host side API, gadget APIs, usb character
 devices and debugfs interfaces.
 
-.. kernel-doc:: include/linux/usb/ch9.h
+.. kernel-doc:: drivers/usb/common/common.c
    :internal:
 
 .. _usb_header:

Signature · 1 line

2.31.1

Wait, no, now I see the warning:
./drivers/usb/common/common.c:1: warning: no structured comments found
instead.

Is that expected? It doesn't feel right to me, what should we be doing instead?

Hi Greg,

On Sat, Apr 24, 2021 at 8:10 AM Greg Kroah-Hartman <[email protected]> wrote:

Quoted 6 lines

Wait, no, now I see the warning:
./drivers/usb/common/common.c:1: warning: no structured comments found
instead.

Is that expected? It doesn't feel right to me, what should we be doing instead?

I think we should do like this instead:

Quoted 6 lines · Fabio Estevam

Hi Greg,

On Sat, Apr 24, 2021 at 8:10 AM Greg Kroah-Hartman <[email protected]> wrote:

Quoted 8 lines

Quoted 6 lines

Wait, no, now I see the warning:
./drivers/usb/common/common.c:1: warning: no structured comments found
instead.

Is that expected? It doesn't feel right to me, what should we be doing instead?

I think we should do like this instead:

Actually I think the fix should be like this:

Documentation/driver-api/usb/usb.rst +0 -0

index 078e981e2b16..cbc76fb51aa9 100644
@@ -109,15 +109,13 @@ well as to make sure they aren't relying on some

HCD-specific behavior.
USB-Standard Types
==================

Documentation/driver-api/usb/usb.rst +4 -6

-In ``<linux/usb/ch9.h>`` you will find the USB data types defined in
-chapter 9 of the USB specification. These data types are used throughout
+In ``drivers/usb/common/common.c`` you will find the USB data types defined
+in chapter 9 of the USB specification. These data types are used throughout
 USB, and in APIs including this host side API, gadget APIs, usb character
 devices and debugfs interfaces.
 
-.. kernel-doc:: include/linux/usb/ch9.h
-   :internal:
-
-.. _usb_header:
+.. kernel-doc:: drivers/usb/common/common.c
+   :export:
 
 Host-Side Data Types and Macros
 ===============================

Does this look good?

Does that produce the same output with the information from those functions? If so, yes, that's fine, I didn't understand the need for _usb_header: there at all...

Can you resend this as a real patch?

Commit 855b35ea96c4 ("usb: common: move function's kerneldoc next to its definition") moved the USB common function documentation out of the .h file and into the .c file. But, we forgot to tell the Documentation where the new information is at, resulting in a build warning of:
include/linux/usb/ch9.h:1: warning: no structured comments found

Fix that up by pointing the documentation at the correct location.

Fixes 855b35ea96c4 ("usb: common: move function's kerneldoc next to its definition")

Cc Chunfeng Yun <[email protected]>

Cc Alan Stern <[email protected]>

Reported-by Stephen Rothwell <[email protected]>

Signed-off-by Greg Kroah-Hartman <[email protected]>

---
 Documentation/driver-api/usb/usb.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

Documentation/driver-api/usb/usb.rst +0 -0

index 078e981e2b16..c08b92558dcb 100644