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

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

[Vinod Koul]

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

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

[Randy Dunlap]

On 11/16/21 2:39 AM, 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(-)
> 

Reviewed-by: Randy Dunlap <rdunlap@infradead.org>

thanks.
-- 
~Randy

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

[Bjorn Andersson]

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
> 

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

[Vinod Koul]

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

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

[PATCH 3/6] phy: qualcomm: qmp: Add missing struct documentation

[Vinod Koul]

dp-* members were added to qmp_phy_combo_cfg but documentation was
missed, so add that.

drivers/phy/qualcomm/phy-qcom-qmp.c:2995: warning: Function parameter or member 'dp_aux_cfg' not described in 'qmp_phy'
drivers/phy/qualcomm/phy-qcom-qmp.c:2995: warning: Function parameter or member 'dp_opts' not described in 'qmp_phy'
drivers/phy/qualcomm/phy-qcom-qmp.c:2995: warning: Function parameter or member 'dp_clks' not described in 'qmp_phy'

Signed-off-by: Vinod Koul <vkoul@kernel.org>
---
 drivers/phy/qualcomm/phy-qcom-qmp.c | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/drivers/phy/qualcomm/phy-qcom-qmp.c b/drivers/phy/qualcomm/phy-qcom-qmp.c
index 456a59d8c7d0..c96639d5f581 100644
--- a/drivers/phy/qualcomm/phy-qcom-qmp.c
+++ b/drivers/phy/qualcomm/phy-qcom-qmp.c
@@ -2973,6 +2973,9 @@ struct qmp_phy_combo_cfg {
  * @qmp: QMP phy to which this lane belongs
  * @lane_rst: lane's reset controller
  * @mode: current PHY mode
+ * @dp_aux_cfg: Display port aux config
+ * @dp_opts: Display port optional config
+ * @dp_clks: Display port clocks
  */
 struct qmp_phy {
 	struct phy *phy;
-- 
2.31.1

Re: [PATCH 3/6] phy: qualcomm: qmp: Add missing struct documentation

[Bjorn Andersson]

On Tue 16 Nov 04:39 CST 2021, Vinod Koul wrote:

> dp-* members were added to qmp_phy_combo_cfg but documentation was
> missed, so add that.
> 
> drivers/phy/qualcomm/phy-qcom-qmp.c:2995: warning: Function parameter or member 'dp_aux_cfg' not described in 'qmp_phy'
> drivers/phy/qualcomm/phy-qcom-qmp.c:2995: warning: Function parameter or member 'dp_opts' not described in 'qmp_phy'
> drivers/phy/qualcomm/phy-qcom-qmp.c:2995: warning: Function parameter or member 'dp_clks' not described in 'qmp_phy'
> 

Reviewed-by: Bjorn Andersson <bjorn.andersson@linaro.org>

Regards,
Bjorn

> Signed-off-by: Vinod Koul <vkoul@kernel.org>
> ---
>  drivers/phy/qualcomm/phy-qcom-qmp.c | 3 +++
>  1 file changed, 3 insertions(+)
> 
> diff --git a/drivers/phy/qualcomm/phy-qcom-qmp.c b/drivers/phy/qualcomm/phy-qcom-qmp.c
> index 456a59d8c7d0..c96639d5f581 100644
> --- a/drivers/phy/qualcomm/phy-qcom-qmp.c
> +++ b/drivers/phy/qualcomm/phy-qcom-qmp.c
> @@ -2973,6 +2973,9 @@ struct qmp_phy_combo_cfg {
>   * @qmp: QMP phy to which this lane belongs
>   * @lane_rst: lane's reset controller
>   * @mode: current PHY mode
> + * @dp_aux_cfg: Display port aux config
> + * @dp_opts: Display port optional config
> + * @dp_clks: Display port clocks
>   */
>  struct qmp_phy {
>  	struct phy *phy;
> -- 
> 2.31.1
> 

[PATCH 4/6] phy: qualcomm: usb-hsic: Fix the kernel-doc warn

[Vinod Koul]

The comment is not kernel-doc one and starts with /**, so fix that.

drivers/phy/qualcomm/phy-qcom-usb-hsic.c:3: 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-usb-hsic.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/drivers/phy/qualcomm/phy-qcom-usb-hsic.c b/drivers/phy/qualcomm/phy-qcom-usb-hsic.c
index 04d18d52f700..716a77748ed8 100644
--- a/drivers/phy/qualcomm/phy-qcom-usb-hsic.c
+++ b/drivers/phy/qualcomm/phy-qcom-usb-hsic.c
@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: GPL-2.0-only
-/**
+/*
  * Copyright (C) 2016 Linaro Ltd
  */
 #include <linux/module.h>
-- 
2.31.1

Re: [PATCH 4/6] phy: qualcomm: usb-hsic: Fix the kernel-doc warn

[Bjorn Andersson]

On Tue 16 Nov 04:39 CST 2021, Vinod Koul wrote:

> The comment is not kernel-doc one and starts with /**, so fix that.
> 
> drivers/phy/qualcomm/phy-qcom-usb-hsic.c:3: warning:
> This comment starts with '/**', but isn't a kernel-doc comment.
> Refer Documentation/doc-guide/kernel-doc.rst

Reviewed-by: Bjorn Andersson <bjorn.andersson@linaro.org>

> 
> Signed-off-by: Vinod Koul <vkoul@kernel.org>
> ---
>  drivers/phy/qualcomm/phy-qcom-usb-hsic.c | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/drivers/phy/qualcomm/phy-qcom-usb-hsic.c b/drivers/phy/qualcomm/phy-qcom-usb-hsic.c
> index 04d18d52f700..716a77748ed8 100644
> --- a/drivers/phy/qualcomm/phy-qcom-usb-hsic.c
> +++ b/drivers/phy/qualcomm/phy-qcom-usb-hsic.c
> @@ -1,5 +1,5 @@
>  // SPDX-License-Identifier: GPL-2.0-only
> -/**
> +/*
>   * Copyright (C) 2016 Linaro Ltd
>   */
>  #include <linux/module.h>
> -- 
> 2.31.1
>