Re: [PATCH net-next v3] net/core: Rephrase function description of __dev_queue_xmit()

[Akira Yokosawa <akiyks@gmail.com>]

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@gmail.com>
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@canb.auug.org.au>
Fixes: c526fd8f9f4f21 ("net: inline dev_queue_xmit()")
Link: https://lore.kernel.org/linux-next/20220503073420.6d3f135d@canb.auug.org.au/
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Cc: Jakub Kicinski <kuba@kernel.org>
Cc: "David S. Miller" <davem@davemloft.net>
Cc: Pavel Begunkov <asml.silence@gmail.com>
---
 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