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

[Greg Kroah-Hartman <gregkh@linuxfoundation.org>]

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