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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-ID: <e42a99c5-1229-4bc6-9437-018d9effe371@infradead.org>
Date: Wed, 13 Nov 2024 22:12:12 -0800
From: Randy Dunlap <rdunlap@...radead.org>
To: anish kumar <yesanishhere@...il.com>, corbet@....net, tj@...nel.org,
 akpm@...ux-foundation.org, ptesarik@...e.com, xavier_qy@....com,
 vbabka@...e.cz, tintinm2017@...il.com
Cc: linux-mm@...ck.org, linux-doc@...r.kernel.org,
 linux-kernel@...r.kernel.org
Subject: Re: [RFC PATCH 0/2] modernize DMA api documentation

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@lst.de/
> 
> 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