| 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 |
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>
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
Hi Randy,
[...]
> I will update everything accordingly.
Sorry for the delay! I just sent a v3 of this patch.
Krzysztof
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:
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(-)