diff mbox series

[v2] PCI: iproc: Fix a non-compliant kernel-doc

Message ID 20210519183829.165982-1-kw@linux.com (mailing list archive)
State Superseded
Delegated to: Bjorn Helgaas
Headers show
Series [v2] PCI: iproc: Fix a non-compliant kernel-doc | expand

Commit Message

Krzysztof Wilczyński May 19, 2021, 6:38 p.m. UTC
Correct a non-compliant kernel-doc used to describe struct and enum
types and functions in the pcie-iproc.c and pcie-iproc-msi.c files, and
resolve the following build time warning related to kernel-doc:

  drivers/pci/controller/pcie-iproc.c:92: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
  drivers/pci/controller/pcie-iproc.c:139: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
  drivers/pci/controller/pcie-iproc.c:153: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
  drivers/pci/controller/pcie-iproc.c:441: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
  drivers/pci/controller/pcie-iproc.c:623: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
  drivers/pci/controller/pcie-iproc.c:901: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst

  drivers/pci/controller/pcie-iproc-msi.c:52: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
  drivers/pci/controller/pcie-iproc-msi.c:68: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst

No change to functionality intended.

Signed-off-by: Krzysztof Wilczyński <kw@linux.com>
---
 drivers/pci/controller/pcie-iproc-msi.c | 16 ++++++++--------
 drivers/pci/controller/pcie-iproc.c     | 14 ++++++++------
 2 files changed, 16 insertions(+), 14 deletions(-)

Comments

Randy Dunlap May 19, 2021, 10:28 p.m. UTC | #1
Hi,

This is a really good cleanup, but there is still one kernel-doc
warning remaining after this patch is applied. Please see below.


On 5/19/21 11:38 AM, Krzysztof Wilczyński wrote:
> Correct a non-compliant kernel-doc used to describe struct and enum
> types and functions in the pcie-iproc.c and pcie-iproc-msi.c files, and
> resolve the following build time warning related to kernel-doc:
> 
>   drivers/pci/controller/pcie-iproc.c:92: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>   drivers/pci/controller/pcie-iproc.c:139: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>   drivers/pci/controller/pcie-iproc.c:153: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>   drivers/pci/controller/pcie-iproc.c:441: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>   drivers/pci/controller/pcie-iproc.c:623: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>   drivers/pci/controller/pcie-iproc.c:901: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
> 
>   drivers/pci/controller/pcie-iproc-msi.c:52: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>   drivers/pci/controller/pcie-iproc-msi.c:68: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
> 
> No change to functionality intended.
> 
> Signed-off-by: Krzysztof Wilczyński <kw@linux.com>
> ---
>  drivers/pci/controller/pcie-iproc-msi.c | 16 ++++++++--------
>  drivers/pci/controller/pcie-iproc.c     | 14 ++++++++------
>  2 files changed, 16 insertions(+), 14 deletions(-)
> 
> diff --git a/drivers/pci/controller/pcie-iproc-msi.c b/drivers/pci/controller/pcie-iproc-msi.c
> index eede4e8f3f75..65ea83d2abfa 100644
> --- a/drivers/pci/controller/pcie-iproc-msi.c
> +++ b/drivers/pci/controller/pcie-iproc-msi.c

> diff --git a/drivers/pci/controller/pcie-iproc.c b/drivers/pci/controller/pcie-iproc.c
> index 02e52f698eeb..8e45288c9abc 100644
> --- a/drivers/pci/controller/pcie-iproc.c
> +++ b/drivers/pci/controller/pcie-iproc.c

> @@ -136,7 +137,7 @@ static const struct iproc_pcie_ob_map paxb_v2_ob_map[] = {
>  };
>  
>  /**
> - * iProc PCIe inbound mapping type
> + * enum iproc_pcie_ib_map_type - iProc PCIe inbound mapping type.
>   */
>  enum iproc_pcie_ib_map_type {
>  	/* for DDR memory */

The above gives me this:

pcie-iproc.c:151: warning: Enum value 'IPROC_PCIE_IB_MAP_MEM' not described in enum 'iproc_pcie_ib_map_type'
pcie-iproc.c:151: warning: Enum value 'IPROC_PCIE_IB_MAP_IO' not described in enum 'iproc_pcie_ib_map_type'
pcie-iproc.c:151: warning: Enum value 'IPROC_PCIE_IB_MAP_INVALID' not described in enum 'iproc_pcie_ib_map_type'


If you could fix that, it would be Nice. :)

Even if not, it's a good cleanup. Thanks.


Acked-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Krzysztof Wilczyński May 19, 2021, 10:49 p.m. UTC | #2
Hi,

> This is a really good cleanup, but there is still one kernel-doc
> warning remaining after this patch is applied. Please see below.
[...]
> > - * iProc PCIe inbound mapping type
> > + * enum iproc_pcie_ib_map_type - iProc PCIe inbound mapping type.
[...]
> 
> The above gives me this:
> 
> pcie-iproc.c:151: warning: Enum value 'IPROC_PCIE_IB_MAP_MEM' not described in enum 'iproc_pcie_ib_map_type'
> pcie-iproc.c:151: warning: Enum value 'IPROC_PCIE_IB_MAP_IO' not described in enum 'iproc_pcie_ib_map_type'
> pcie-iproc.c:151: warning: Enum value 'IPROC_PCIE_IB_MAP_INVALID' not described in enum 'iproc_pcie_ib_map_type'
> 
> 
> If you could fix that, it would be Nice. :)
> 
> Even if not, it's a good cleanup. Thanks.

Doh!  Apologies!  This is my bad - correcting the format of the
kernel-doc made the parser go and check for the fields to be properly
documented, thus this new warning.  I need to also take care about this
too, a very good point!

Thank you for catching this!  I will update everything accordingly.

Krzysztof
Krzysztof Wilczyński July 2, 2021, 8:42 p.m. UTC | #3
Hi Randy,

[...]
> I will update everything accordingly.

Sorry for the delay!  I just sent a v3 of this patch.

	Krzysztof
diff mbox series

Patch

diff --git a/drivers/pci/controller/pcie-iproc-msi.c b/drivers/pci/controller/pcie-iproc-msi.c
index eede4e8f3f75..65ea83d2abfa 100644
--- a/drivers/pci/controller/pcie-iproc-msi.c
+++ b/drivers/pci/controller/pcie-iproc-msi.c
@@ -49,14 +49,14 @@  enum iproc_msi_reg {
 struct iproc_msi;
 
 /**
- * iProc MSI group
- *
- * One MSI group is allocated per GIC interrupt, serviced by one iProc MSI
- * event queue.
+ * struct iproc_msi_grp - iProc MSI group
  *
  * @msi: pointer to iProc MSI data
  * @gic_irq: GIC interrupt
  * @eq: Event queue number
+ *
+ * One MSI group is allocated per GIC interrupt, serviced by one iProc MSI
+ * event queue.
  */
 struct iproc_msi_grp {
 	struct iproc_msi *msi;
@@ -65,10 +65,7 @@  struct iproc_msi_grp {
 };
 
 /**
- * iProc event queue based MSI
- *
- * Only meant to be used on platforms without MSI support integrated into the
- * GIC.
+ * struct iproc_msi - iProc event queue based MSI
  *
  * @pcie: pointer to iProc PCIe data
  * @reg_offsets: MSI register offsets
@@ -89,6 +86,9 @@  struct iproc_msi_grp {
  * @eq_cpu: pointer to allocated memory region for MSI event queues
  * @eq_dma: DMA address of MSI event queues
  * @msi_addr: MSI address
+ *
+ * Only meant to be used on platforms without MSI support integrated into the
+ * GIC.
  */
 struct iproc_msi {
 	struct iproc_pcie *pcie;
diff --git a/drivers/pci/controller/pcie-iproc.c b/drivers/pci/controller/pcie-iproc.c
index 02e52f698eeb..8e45288c9abc 100644
--- a/drivers/pci/controller/pcie-iproc.c
+++ b/drivers/pci/controller/pcie-iproc.c
@@ -89,7 +89,8 @@ 
 #define IPROC_PCIE_REG_INVALID		0xffff
 
 /**
- * iProc PCIe outbound mapping controller specific parameters
+ * struct iproc_pcie_ob_map - iProc PCIe outbound mapping controller specific
+ *			      parameters.
  *
  * @window_sizes: list of supported outbound mapping window sizes in MB
  * @nr_sizes: number of supported outbound mapping window sizes
@@ -136,7 +137,7 @@  static const struct iproc_pcie_ob_map paxb_v2_ob_map[] = {
 };
 
 /**
- * iProc PCIe inbound mapping type
+ * enum iproc_pcie_ib_map_type - iProc PCIe inbound mapping type.
  */
 enum iproc_pcie_ib_map_type {
 	/* for DDR memory */
@@ -150,7 +151,8 @@  enum iproc_pcie_ib_map_type {
 };
 
 /**
- * iProc PCIe inbound mapping controller specific parameters
+ * struct iproc_pcie_ib_map - iProc PCIe inbound mapping controller specific
+ *			      parameters.
  *
  * @type: inbound mapping region type
  * @size_unit: inbound mapping region size unit, could be SZ_1K, SZ_1M, or
@@ -437,7 +439,7 @@  static inline void iproc_pcie_write_reg(struct iproc_pcie *pcie,
 	writel(val, pcie->base + offset);
 }
 
-/**
+/*
  * APB error forwarding can be disabled during access of configuration
  * registers of the endpoint device, to prevent unsupported requests
  * (typically seen during enumeration with multi-function devices) from
@@ -619,7 +621,7 @@  static int iproc_pcie_config_read(struct pci_bus *bus, unsigned int devfn,
 	return PCIBIOS_SUCCESSFUL;
 }
 
-/**
+/*
  * Note access to the configuration registers are protected at the higher layer
  * by 'pci_lock' in drivers/pci/access.c
  */
@@ -897,7 +899,7 @@  static inline int iproc_pcie_ob_write(struct iproc_pcie *pcie, int window_idx,
 	return 0;
 }
 
-/**
+/*
  * Some iProc SoCs require the SW to configure the outbound address mapping
  *
  * Outbound address translation: