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

* [PATCH v2] PCI: iproc: Fix a non-compliant kernel-doc
@ 2021-05-19 18:38 ` Krzysztof Wilczyński
  0 siblings, 0 replies; 8+ messages in thread
From: Krzysztof Wilczyński @ 2021-05-19 18:38 UTC (permalink / raw)
  To: Ray Jui
  Cc: Bjorn Helgaas, Lorenzo Pieralisi, Rob Herring, Scott Branden,
	bcm-kernel-feedback-list, linux-pci, linux-arm-kernel

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
@@ -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:
-- 
2.31.1


^ permalink raw reply related	[flat|nested] 8+ messages in thread