linux-kernel - Re: [PATCH net-next] net/skbuff: fix up kernel-doc placement

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: <20190212.095520.2293054975357585380.davem@davemloft.net>
Date:   Tue, 12 Feb 2019 09:55:20 -0800 (PST)
From:   David Miller <davem@...emloft.net>
To:     briannorris@...omium.org
Cc:     netdev@...r.kernel.org, linux-kernel@...r.kernel.org
Subject: Re: [PATCH net-next] net/skbuff: fix up kernel-doc placement

From: Brian Norris <briannorris@...omium.org>
Date: Mon, 11 Feb 2019 13:02:25 -0800

> There are several skb_* functions where the locked and unlocked
> functions are confusingly documented. For several of them, the
> kernel-doc for the unlocked version is placed above the locked version,
> which to the casual reader makes it seems like the locked version "takes
> no locks and you must therefore hold required locks before calling it."
> 
> One can see, for example, that this link claims to document
> skb_queue_head(), while instead describing __skb_queue_head().
> 
> https://www.kernel.org/doc/html/latest/networking/kapi.html#c.skb_queue_head
> 
> The correct documentation for skb_queue_head() is also included further
> down the page.
> 
> This diff tested via:
> 
>   $ scripts/kernel-doc -rst include/linux/skbuff.h net/core/skbuff.c
> 
> No new warnings were seen, and the output makes a little more sense.
> 
> Signed-off-by: Brian Norris <briannorris@...omium.org>

Applied, thanks Brian.