From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-15.3 required=3.0 tests=BAYES_00, HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER,INCLUDES_PATCH, MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,USER_AGENT_SANE_1 autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id D1223C43461 for ; Sat, 24 Apr 2021 15:12:03 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id AED7A613C1 for ; Sat, 24 Apr 2021 15:12:03 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231892AbhDXPMk (ORCPT ); Sat, 24 Apr 2021 11:12:40 -0400 Received: from netrider.rowland.org ([192.131.102.5]:35993 "HELO netrider.rowland.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with SMTP id S232051AbhDXPMh (ORCPT ); Sat, 24 Apr 2021 11:12:37 -0400 Received: (qmail 313052 invoked by uid 1000); 24 Apr 2021 11:11:57 -0400 Date: Sat, 24 Apr 2021 11:11:57 -0400 From: Alan Stern To: Fabio Estevam Cc: gregkh@linuxfoundation.org, chunfeng.yun@mediatek.com, sfr@canb.auug.org.au, linux-usb@vger.kernel.org, linux-next@vger.kernel.org, corbet@lwn.net, linux-doc@vger.kernel.org Subject: Re: [PATCH] usb: Fix up movement of USB core kerneldoc location Message-ID: <20210424151157.GA312740@rowland.harvard.edu> References: <20210424135103.2476670-1-festevam@gmail.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20210424135103.2476670-1-festevam@gmail.com> User-Agent: Mutt/1.10.1 (2018-07-13) Precedence: bulk List-ID: X-Mailing-List: linux-usb@vger.kernel.org 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 > Signed-off-by: Fabio Estevam > --- > 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 ```` 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 >