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

Bjorn Andersson
2021-11-18T00:18:36Z

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@kernel.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.

> + * 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".

Regards,
Bjorn

> + * @offset: register offset.
> + * @mask: register bitmask specifying what should be updated
> + * @val: value to write.
> */
> static inline void usb_phy_write_readback(struct usb_phy *phy_dwc3,
> u32 offset,
> @@ -171,11 +172,11 @@ static int wait_for_latch(void __iomem *addr)
> }
>
> /**
> - * Write SSPHY register
> + * usb_ss_write_phycreg - Write SSPHY register
> *
> - * @base - QCOM DWC3 PHY base virtual address.
> - * @addr - SSPHY address to write.
> - * @val - value to write.
> + * @phy_dwc3: QCOM DWC3 PHY base virtual address.
> + * @addr: SSPHY address to write.
> + * @val: value to write.
> */
> static int usb_ss_write_phycreg(struct usb_phy *phy_dwc3,
> u32 addr, u32 val)
> @@ -209,10 +210,11 @@ static int usb_ss_write_phycreg(struct usb_phy *phy_dwc3,
> }
>
> /**
> - * Read SSPHY register.
> + * usb_ss_read_phycreg - Read SSPHY register.
> *
> - * @base - QCOM DWC3 PHY base virtual address.
> - * @addr - SSPHY address to read.
> + * @phy_dwc3: QCOM DWC3 PHY base virtual address.
> + * @addr: SSPHY address to read.
> + * @val: pointer in which read is store.
> */
> static int usb_ss_read_phycreg(struct usb_phy *phy_dwc3,
> u32 addr, u32 *val)
> --
> 2.31.1
>