linux-kernel - Re: [PATCH 2/6] phy: qualcomm: ipq806x-usb: Fix kernel-doc style

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Date:   Sat, 20 Nov 2021 11:30:23 +0530
From:   Vinod Koul <vkoul@...nel.org>
To:     Bjorn Andersson <bjorn.andersson@...aro.org>
Cc:     Kishon Vijay Abraham I <kishon@...com>,
        linux-phy@...ts.infradead.org, Andy Gross <agross@...nel.org>,
        linux-arm-msm@...r.kernel.org, linux-kernel@...r.kernel.org
Subject: Re: [PATCH 2/6] phy: qualcomm: ipq806x-usb: Fix kernel-doc style

On 17-11-21, 18:18, Bjorn Andersson wrote:
> On Tue 16 Nov 04:39 CST 2021, Vinod Koul wrote:
> 
> > The functions are documented but there were style issues, so fix
> > the style and add missing description for phy_dwc3
> > 
> > drivers/phy/qualcomm/phy-qcom-ipq806x-usb.c:130:
> > drivers/phy/qualcomm/phy-qcom-ipq806x-usb.c:174:
> > drivers/phy/qualcomm/phy-qcom-ipq806x-usb.c:212: warning:
> > This comment starts with '/**', but isn't a kernel-doc comment.
> > Refer Documentation/doc-guide/kernel-doc.rst
> > 
> > Signed-off-by: Vinod Koul <vkoul@...nel.org>
> > ---
> >  drivers/phy/qualcomm/phy-qcom-ipq806x-usb.c | 26 +++++++++++----------
> >  1 file changed, 14 insertions(+), 12 deletions(-)
> > 
> > diff --git a/drivers/phy/qualcomm/phy-qcom-ipq806x-usb.c b/drivers/phy/qualcomm/phy-qcom-ipq806x-usb.c
> > index bfff0c8c9130..e1b8fa911416 100644
> > --- a/drivers/phy/qualcomm/phy-qcom-ipq806x-usb.c
> > +++ b/drivers/phy/qualcomm/phy-qcom-ipq806x-usb.c
> > @@ -127,12 +127,13 @@ struct phy_drvdata {
> >  };
> >  
> >  /**
> > - * Write register and read back masked value to confirm it is written
> > + * usb_phy_write_readback - Write register and read back masked value to
> 
> "Writing kernel-doc" indicates that you should have some parenthesis
> after that function.

Heh, it does not warn :(, will update this
> 
> > + * confirm it is written
> >   *
> > - * @base - QCOM DWC3 PHY base virtual address.
> > - * @offset - register offset.
> > - * @mask - register bitmask specifying what should be updated
> > - * @val - value to write.
> > + * @phy_dwc3: QCOM DWC3 PHY base virtual address.
> 
> I guess this was "base" at some point? As you're fixing up the
> kerneldoc, it would be nice to correct this to say something like
> "usb_phy context".

Why did I miss this one :(, yeah will update this

-- 
~Vinod