Re: [RFC PATCH 0/2] modernize DMA api documentation

From: Randy Dunlap
Date: Thu Nov 14 2024 - 01:12:35 EST


Hi--

On 11/12/24 10:34 PM, anish kumar wrote:
> Dear maintainers,
>
> This patch series is inspired by the ongoing discussion in the following thread:
> https://lore.kernel.org/lkml/20241111063847.GB23992@xxxxxx/
>
> As part of an effort to modernize the documentation, the first patch in
> this series converts the relevant document to use kernel-doc comments directly
> within the source code, replacing the previous method of manually adding
> documentation. This change will help streamline the documentation workflow and
> ensure it remains synchronized with the code.
>
> I am still getting below errors and wondering if there is a better
> way to write this patch.
>
> /home/ANT.AMAZON.COM/anishkmr/Downloads/linux/Documentation/core-api/dma-api:89:
> ./mm/dmapool.c:229: WARNING: Duplicate C declaration, also defined at
> core-api/mm-api:224. Declaration is:
> '.. c:function:: struct dma_pool *dma_pool_create (const char *name,
> struct device *dev, size_t size, size_t align, size_t boundary)'.
>
> /home/ANT.AMAZON.COM/anishkmr/Downloads/linux/Documentation/core-api/dma-api:92:
> ./mm/dmapool.c:420: WARNING: Duplicate C declaration, also defined at
> core-api/mm-api:404. Declaration is:
> '.. c:function:: void *dma_pool_alloc (struct dma_pool *pool, gfp_t mem_flags,
> dma_addr_t *handle)'.
>
> /home/ANT.AMAZON.COM/anishkmr/Downloads/linux/Documentation/core-api/dma-api:98:
> ./mm/dmapool.c:229: WARNING: Duplicate C declaration, also defined at
> core-api/mm-api:224. Declaration is:
> '.. c:function:: struct dma_pool *dma_pool_create (const char *name,
> struct device *dev, size_t size, size_t align, size_t boundary)'.
>
> /home/ANT.AMAZON.COM/anishkmr/Downloads/linux/Documentation/core-api/dma-api:101:
> ./mm/dmapool.c:466: WARNING: Duplicate C declaration, also defined at
> core-api/mm-api:450. Declaration is:
> '.. c:function:: void dma_pool_free (struct dma_pool *pool, void *vaddr,
> dma_addr_t dma)'.
>
> /home/ANT.AMAZON.COM/anishkmr/Downloads/linux/Documentation/core-api/dma-api:104:
> ./mm/dmapool.c:366: WARNING: Duplicate C declaration, also defined at
> core-api/mm-api:360.
>

If you are going to add these APIs in dma-api.rst, you need to remove them from
mm-api.rst (IMO). That should remove these Duplicate warnings.


> Thank you for considering this patch. I look forward to your feedback.
>
> anish kumar (2):
> dmapool: Improve dma api kernel-doc comments
> dmapool: Documentation: use the kernel-doc comment
>
> Documentation/core-api/dma-api.rst | 66 ++++++------------------------
> mm/dmapool.c | 40 ++++++++++++------
> 2 files changed, 40 insertions(+), 66 deletions(-)
>

--
~Randy