On 2022/05/07 17:46, Bagas Sanjaya wrote: > Commit c526fd8f9f4f21 ("net: inline dev_queue_xmit()") inlines > dev_queue_xmit() that contains comment quote from Ben Greear, which > originates from commit af191367a75262 ("[NET]: Document ->hard_start_xmit() > locking in comments.").It triggers htmldocs warning: What I asked was the explanation of *why* the inlining of the function caused the new warning. Your explanation above tries to tell *what* the offending commit did, which is not what I asked. Furthermore, your explanation is not accurate in that the comment block does not belong to dev_queue_xmit() but to __dev_queue_xmit(). After seeking the answer myself, I reached a conclusion that it is wrong to meddle with the comment block. So, appended below is my version of the fix with the answer to Stephen's question, "I am not sure why this has turned up just now." Stephen, Jakub, what do you think? Thanks, Akira ----8<-------------- From: Akira Yokosawa <akiyks@xxxxxxxxx> Subject: [PATCH -next] net/core: Hide __dev_queue_xmit()'s kernel-doc Commit c526fd8f9f4f21 ("net: inline dev_queue_xmit()") added export of __dev_queue_exit() to cope with inlining of its wrapper functions dev_queue_xmit() and dev_queue_xmit_accel(). This made __dev_queue_exit()'s comment block visible to Sphinx processing in "make htmldocs" because Documentation/networking/kapi.rst has the directive of: .. kernel-doc:: net/core/dev.c :export: Unfortunately, the kernel-doc style comment has a number of issues when parsed as RestructuredText. Stephen reported a new warning message from "make htmldocs" caused by one of such issues. The leading "__" in the function name indicates that it is an internal API and should not be widely used. Exposing documentation of such a function in HTML and PDF documentations does not make sense. For the time being, hide the kernel-doc style comment from Sphinx processing by removing the kernel-doc marker of "/**". Proper kernel-doc comments should be added to the inlined wrapper functions, which is deferred to those who are familiar with those netdev APIs. Reported-by: Stephen Rothwell <sfr@xxxxxxxxxxxxxxxx> Fixes: c526fd8f9f4f21 ("net: inline dev_queue_xmit()") Link: https://lore.kernel.org/linux-next/20220503073420.6d3f135d@xxxxxxxxxxxxxxxx/ Signed-off-by: Akira Yokosawa <akiyks@xxxxxxxxx> Cc: Jakub Kicinski <kuba@xxxxxxxxxx> Cc: "David S. Miller" <davem@xxxxxxxxxxxxx> Cc: Pavel Begunkov <asml.silence@xxxxxxxxx> --- net/core/dev.c | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/net/core/dev.c b/net/core/dev.c index c2d73595a7c3..a97fd413d705 100644 --- a/net/core/dev.c +++ b/net/core/dev.c @@ -4085,8 +4085,7 @@ struct netdev_queue *netdev_core_pick_tx(struct net_device *dev, return netdev_get_tx_queue(dev, queue_index); } -/** - * __dev_queue_xmit - transmit a buffer +/* __dev_queue_xmit - transmit a buffer * @skb: buffer to transmit * @sb_dev: suboordinate device used for L2 forwarding offload * -- 2.25.1