| Message ID | 20210424104715.2793760-1-gregkh@linuxfoundation.org (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | USB: fix up movement of USB core kerneldoc location | expand |
On Sat, Apr 24, 2021 at 12:47:15PM +0200, Greg Kroah-Hartman wrote: > 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 <chunfeng.yun@mediatek.com> > Cc: Alan Stern <stern@rowland.harvard.edu> > Reported-by: Stephen Rothwell <sfr@canb.auug.org.au> > Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> > --- > Documentation/driver-api/usb/usb.rst | 2 +- > 1 file changed, 1 insertion(+), 1 deletion(-) > > diff --git a/Documentation/driver-api/usb/usb.rst b/Documentation/driver-api/usb/usb.rst > index 078e981e2b16..c08b92558dcb 100644 > --- a/Documentation/driver-api/usb/usb.rst > +++ b/Documentation/driver-api/usb/usb.rst > @@ -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: > -- > 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? thanks, greg k-h
Hi Greg, On Sat, Apr 24, 2021 at 8:10 AM Greg Kroah-Hartman <gregkh@linuxfoundation.org> wrote: > 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: --- a/Documentation/driver-api/usb/usb.rst +++ b/Documentation/driver-api/usb/usb.rst @@ -114,9 +114,6 @@ 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: Since ch9.h does not contain any structure/inline functions, it does not contain any comment, so it should be just removed from the kernel-doc section. A similar issue has been fixed here: https://patchwork.kernel.org/project/dri-devel/patch/20190920193558.89815-2-sean@poorly.run/ Regards, Fabio Estevam
On Sat, Apr 24, 2021 at 8:25 AM Fabio Estevam <festevam@gmail.com> wrote: > > Hi Greg, > > On Sat, Apr 24, 2021 at 8:10 AM Greg Kroah-Hartman > <gregkh@linuxfoundation.org> wrote: > > > 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: diff --git a/Documentation/driver-api/usb/usb.rst b/Documentation/driver-api/usb/usb.rst index 078e981e2b16..cbc76fb51aa9 100644 --- a/Documentation/driver-api/usb/usb.rst +++ b/Documentation/driver-api/usb/usb.rst @@ -109,15 +109,13 @@ well as to make sure they aren't relying on some HCD-specific behavior. USB-Standard Types ================== -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? Thanks
On Sat, Apr 24, 2021 at 09:29:00AM -0300, Fabio Estevam wrote: > On Sat, Apr 24, 2021 at 8:25 AM Fabio Estevam <festevam@gmail.com> wrote: > > > > Hi Greg, > > > > On Sat, Apr 24, 2021 at 8:10 AM Greg Kroah-Hartman > > <gregkh@linuxfoundation.org> wrote: > > > > > 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: > > diff --git a/Documentation/driver-api/usb/usb.rst > b/Documentation/driver-api/usb/usb.rst > index 078e981e2b16..cbc76fb51aa9 100644 > --- a/Documentation/driver-api/usb/usb.rst > +++ b/Documentation/driver-api/usb/usb.rst > @@ -109,15 +109,13 @@ well as to make sure they aren't relying on some > HCD-specific behavior. > USB-Standard Types > ================== > > -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? thanks, greg k-h
Hi Greg, On Sat, Apr 24, 2021 at 9:43 AM Greg Kroah-Hartman <gregkh@linuxfoundation.org> wrote: > 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... Yes, I looked at the generated HTML and it looks good. > Can you resend this as a real patch? Sure, will do. Regards, Fabio Estevam
On 4/24/21 3:47 AM, Greg Kroah-Hartman wrote: > 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 <chunfeng.yun@mediatek.com> > Cc: Alan Stern <stern@rowland.harvard.edu> > Reported-by: Stephen Rothwell <sfr@canb.auug.org.au> > Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> > --- > Documentation/driver-api/usb/usb.rst | 2 +- > 1 file changed, 1 insertion(+), 1 deletion(-) > > diff --git a/Documentation/driver-api/usb/usb.rst b/Documentation/driver-api/usb/usb.rst > index 078e981e2b16..c08b92558dcb 100644 > --- a/Documentation/driver-api/usb/usb.rst > +++ b/Documentation/driver-api/usb/usb.rst > @@ -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. > Sorry to go backwards in time here, but what was wrong with > -.. kernel-doc:: include/linux/usb/ch9.h .. kernel-doc: include/uapi/linux/usb/ch9.h here? > +.. kernel-doc:: drivers/usb/common/common.c > :internal: > > .. _usb_header: > thanks.
diff --git a/Documentation/driver-api/usb/usb.rst b/Documentation/driver-api/usb/usb.rst index 078e981e2b16..c08b92558dcb 100644 --- a/Documentation/driver-api/usb/usb.rst +++ b/Documentation/driver-api/usb/usb.rst @@ -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:
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 <chunfeng.yun@mediatek.com> Cc: Alan Stern <stern@rowland.harvard.edu> Reported-by: Stephen Rothwell <sfr@canb.auug.org.au> Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> --- Documentation/driver-api/usb/usb.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)