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

[Randy Dunlap]

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