[PATCH] usb: Fix up movement of USB core kerneldoc location

[PATCH] usb: Fix up movement of USB core kerneldoc location

[Fabio Estevam]

Commit 855b35ea96c4 ("usb: common: move function's kerneldoc next to its
definition") moved the USB common function documentation out of the
linux/usb/ch9.h header file into drivers/usb/common/common.c and
drivers/usb/common/debug.c, which causes the following 'make htmldocs'
build warning:

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")
Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
Signed-off-by: Fabio Estevam <festevam@gmail.com>
---
Hi,

I compared the generated HTML and now the following functions are
also documented after this patch:

usb_decode_interval()
of_usb_get_dr_mode_by_phy()
of_usb_host_tpl_support()
of_usb_update_otg_caps()
usb_of_get_companion_dev()

They were not documented prior to 855b35ea96c4.

Please let me know if this is OK or not.

 Documentation/driver-api/usb/usb.rst | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/Documentation/driver-api/usb/usb.rst b/Documentation/driver-api/usb/usb.rst
index 078e981e2b16..543e70434da2 100644
--- a/Documentation/driver-api/usb/usb.rst
+++ b/Documentation/driver-api/usb/usb.rst
@@ -109,15 +109,16 @@ 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
-USB, and in APIs including this host side API, gadget APIs, usb character
-devices and debugfs interfaces.
+In ``drivers/usb/common/common.c`` and ``drivers/usb/common/debug.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:
+.. kernel-doc:: drivers/usb/common/common.c
+   :export:
 
-.. _usb_header:
+.. kernel-doc:: drivers/usb/common/debug.c
+   :export:
 
 Host-Side Data Types and Macros
 ===============================
-- 
2.25.1

Re: [PATCH] usb: Fix up movement of USB core kerneldoc location

[Greg KH]

On Sat, Apr 24, 2021 at 10:51:03AM -0300, Fabio Estevam wrote:
> Commit 855b35ea96c4 ("usb: common: move function's kerneldoc next to its
> definition") moved the USB common function documentation out of the
> linux/usb/ch9.h header file into drivers/usb/common/common.c and
> drivers/usb/common/debug.c, which causes the following 'make htmldocs'
> build warning:
> 
> 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")
> Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
> Signed-off-by: Fabio Estevam <festevam@gmail.com>
> ---
> Hi,
> 
> I compared the generated HTML and now the following functions are
> also documented after this patch:
> 
> usb_decode_interval()
> of_usb_get_dr_mode_by_phy()
> of_usb_host_tpl_support()
> of_usb_update_otg_caps()
> usb_of_get_companion_dev()
> 
> They were not documented prior to 855b35ea96c4.
> 
> Please let me know if this is OK or not.

Looks great, thank you for this, I'll go queue it up now!

greg k-h

Re: [PATCH] usb: Fix up movement of USB core kerneldoc location

[Alan Stern]

On Sat, Apr 24, 2021 at 10:51:03AM -0300, Fabio Estevam wrote:
> Commit 855b35ea96c4 ("usb: common: move function's kerneldoc next to its
> definition") moved the USB common function documentation out of the
> linux/usb/ch9.h header file into drivers/usb/common/common.c and
> drivers/usb/common/debug.c, which causes the following 'make htmldocs'
> build warning:
> 
> 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")
> Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
> Signed-off-by: Fabio Estevam <festevam@gmail.com>
> ---
> Hi,
> 
> I compared the generated HTML and now the following functions are
> also documented after this patch:
> 
> usb_decode_interval()
> of_usb_get_dr_mode_by_phy()
> of_usb_host_tpl_support()
> of_usb_update_otg_caps()
> usb_of_get_companion_dev()
> 
> They were not documented prior to 855b35ea96c4.
> 
> Please let me know if this is OK or not.
> 
>  Documentation/driver-api/usb/usb.rst | 15 ++++++++-------
>  1 file changed, 8 insertions(+), 7 deletions(-)
> 
> diff --git a/Documentation/driver-api/usb/usb.rst b/Documentation/driver-api/usb/usb.rst
> index 078e981e2b16..543e70434da2 100644
> --- a/Documentation/driver-api/usb/usb.rst
> +++ b/Documentation/driver-api/usb/usb.rst
> @@ -109,15 +109,16 @@ 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
> -USB, and in APIs including this host side API, gadget APIs, usb character
> -devices and debugfs interfaces.
> +In ``drivers/usb/common/common.c`` and ``drivers/usb/common/debug.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.

This is quite wrong.

The USB data types defined in chapter 9 of the USB specification can 
actually be found in include/uapi/linux/usb/ch9.h.  What 
drivers/usb/common/common.c contains is the definitions of the functions 
declared in include/linux/usb/ch9.h, which is a different file (although 
it does #include the file in include/uapi/linux/usb/).

drivers/usb/common/debug.c, on the other hand, contains definitions of 
various functions used for debugging output.  If those functions are 
declared in a header file anywhere, I can't see it.

Alan Stern

> -.. kernel-doc:: include/linux/usb/ch9.h
> -   :internal:
> +.. kernel-doc:: drivers/usb/common/common.c
> +   :export:
>  
> -.. _usb_header:
> +.. kernel-doc:: drivers/usb/common/debug.c
> +   :export:
>  
>  Host-Side Data Types and Macros
>  ===============================
> -- 
> 2.25.1
> 

Re: [PATCH] usb: Fix up movement of USB core kerneldoc location

[Fabio Estevam]

Hi Alan,

On Sat, Apr 24, 2021 at 12:11 PM Alan Stern <stern@rowland.harvard.edu> wrote:

> This is quite wrong.
>
> The USB data types defined in chapter 9 of the USB specification can
> actually be found in include/uapi/linux/usb/ch9.h.  What
> drivers/usb/common/common.c contains is the definitions of the functions
> declared in include/linux/usb/ch9.h, which is a different file (although
> it does #include the file in include/uapi/linux/usb/).

It seems we can no longer refer include/linux/usb/ch9.h inside the
kerneldoc marker, as this file does not contain any comments anymore.

Would this change on top of this patch be OK?

Thanks

diff --git a/Documentation/driver-api/usb/usb.rst
b/Documentation/driver-api/usb/usb.rst
index 543e70434da2..251cab7cacd7 100644
--- a/Documentation/driver-api/usb/usb.rst
+++ b/Documentation/driver-api/usb/usb.rst
@@ -109,16 +109,10 @@ well as to make sure they aren't relying on some
HCD-specific behavior.
 USB-Standard Types
 ==================

-In ``drivers/usb/common/common.c`` and ``drivers/usb/common/debug.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:: drivers/usb/common/common.c
-   :export:
-
-.. kernel-doc:: drivers/usb/common/debug.c
-   :export:
+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
+USB, and in APIs including this host side API, gadget APIs, usb character
+devices and debugfs interfaces.

 Host-Side Data Types and Macros
 ===============================
-- 
2.25.1

[PATCH] USB: fix up movement of USB core kerneldoc location

[Greg Kroah-Hartman]

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

Re: [PATCH] USB: fix up movement of USB core kerneldoc location

[Greg Kroah-Hartman]

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

Re: [PATCH] USB: fix up movement of USB core kerneldoc location

[Fabio Estevam]

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

Re: [PATCH] USB: fix up movement of USB core kerneldoc location

[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

Re: [PATCH] USB: fix up movement of USB core kerneldoc location

[Greg Kroah-Hartman]

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

Re: [PATCH] USB: fix up movement of USB core kerneldoc location

[Fabio Estevam]

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

Re: [PATCH] USB: fix up movement of USB core kerneldoc location

[Randy Dunlap]

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.
-- 
~Randy