| Message ID | 20220503072949.27336-1-bagasdotme@gmail.com (mailing list archive) |
|---|---|
| State | Changes Requested |
| Delegated to: | Netdev Maintainers |
| Headers | show |
| Series | [net-next] net/core: Remove comment quote for __dev_queue_xmit() | expand |
On Tue, 3 May 2022 14:29:49 +0700 Bagas Sanjaya wrote: > - * ----------------------------------------------------------------------------------- > - * I notice this method can also return errors from the queue disciplines, > - * including NET_XMIT_DROP, which is a positive value. So, errors can also > - * be positive. > - * > - * Regardless of the return value, the skb is consumed, so it is currently > - * difficult to retry a send to this method. (You can bump the ref count > - * before sending to hold a reference for retry if you are careful.) > - * > - * When calling this method, interrupts MUST be enabled. This is because > - * the BH enable code must have IRQs enabled so that it will not deadlock. > - * --BLG > + * This method can also return positive errno code from the queue > + * disciplines (including NET_XMIT_DROP). > + * > + * Note that regardless of the return value, the skb is consumed > + * anyway, so it is currently difficult to retry sending to this > + * method. Why drop almost half of the comment if the problem is just the ---- banner?
On 5/4/22 08:03, Jakub Kicinski wrote: > On Tue, 3 May 2022 14:29:49 +0700 Bagas Sanjaya wrote: >> - * ----------------------------------------------------------------------------------- >> - * I notice this method can also return errors from the queue disciplines, >> - * including NET_XMIT_DROP, which is a positive value. So, errors can also >> - * be positive. >> - * >> - * Regardless of the return value, the skb is consumed, so it is currently >> - * difficult to retry a send to this method. (You can bump the ref count >> - * before sending to hold a reference for retry if you are careful.) >> - * >> - * When calling this method, interrupts MUST be enabled. This is because >> - * the BH enable code must have IRQs enabled so that it will not deadlock. >> - * --BLG >> + * This method can also return positive errno code from the queue >> + * disciplines (including NET_XMIT_DROP). >> + * >> + * Note that regardless of the return value, the skb is consumed >> + * anyway, so it is currently difficult to retry sending to this >> + * method. > > Why drop almost half of the comment if the problem is just the ---- > banner? I can't think of preserving delineation between actual documentation and the quote without messing up kernel-doc. Actually the "--BLG" signature is the culprit.
Hi, On Wed, 4 May 2022 11:28:51 +0700, Bagas Sanjaya wrote: > On 5/4/22 08:03, Jakub Kicinski wrote: [...] >> Why drop almost half of the comment if the problem is just the ---- >> banner? > > I can't think of preserving delineation between actual documentation > and the quote without messing up kernel-doc. Actually, it is possible. See "Block Quotes" in ReST documentation at: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#block-quotes kernel-doc is basically ReST within comment blocks with several kernel-doc specific implicit/explicit markers. Thanks, Akira > > Actually the "--BLG" signature is the culprit.
On Wed, 4 May 2022 22:43:12 +0900 Akira Yokosawa wrote: > > I can't think of preserving delineation between actual documentation > > and the quote without messing up kernel-doc. That's not what I'm complaining about, I'm saying that you rewrote the documentation. There were 3 paragraphs now there are 2. > Actually, it is possible. > > See "Block Quotes" in ReST documentation at: > https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#block-quotes > > kernel-doc is basically ReST within comment blocks with several kernel-doc > specific implicit/explicit markers. With all due respect I don't even know who (what?) "BLG" is. Let's just get rid of the delineation and the signature and make the text of the quote normal documentation. > > Actually the "--BLG" signature is the culprit.
[+To: Ben] [-Cc: unreachable addresses] Hi, On 2022/05/04 23:37, Jakub Kicinski wrote: > On Wed, 4 May 2022 22:43:12 +0900 Akira Yokosawa wrote: >>> I can't think of preserving delineation between actual documentation >>> and the quote without messing up kernel-doc. > > That's not what I'm complaining about, I'm saying that you rewrote > the documentation. There were 3 paragraphs now there are 2. > >> Actually, it is possible. >> >> See "Block Quotes" in ReST documentation at: >> https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#block-quotes >> >> kernel-doc is basically ReST within comment blocks with several kernel-doc >> specific implicit/explicit markers. > > With all due respect I don't even know who (what?) "BLG" is. In case this might help, this comment block was added in commit af191367a752 ("[NET]: Document ->hard_start_xmit() locking in comments.") authored by Ben way back in 2005. Ben, if you want to see the circumstances, here is a link to the lore archive. https://lore.kernel.org/all/20220504073707.5bd851b0@kernel.org/#r > > Let's just get rid of the delineation and the signature and make > the text of the quote normal documentation. I'm not sure but Ben might be interested in helping rephrase the quote. Thanks, Akira > >>> Actually the "--BLG" signature is the culprit. >
diff --git a/net/core/dev.c b/net/core/dev.c index d127164771f222..b5273f820ca840 100644 --- a/net/core/dev.c +++ b/net/core/dev.c @@ -4098,18 +4098,13 @@ struct netdev_queue *netdev_core_pick_tx(struct net_device *dev, * guarantee the frame will be transmitted as it may be dropped due * to congestion or traffic shaping. * - * ----------------------------------------------------------------------------------- - * I notice this method can also return errors from the queue disciplines, - * including NET_XMIT_DROP, which is a positive value. So, errors can also - * be positive. - * - * Regardless of the return value, the skb is consumed, so it is currently - * difficult to retry a send to this method. (You can bump the ref count - * before sending to hold a reference for retry if you are careful.) - * - * When calling this method, interrupts MUST be enabled. This is because - * the BH enable code must have IRQs enabled so that it will not deadlock. - * --BLG + * This method can also return positive errno code from the queue + * disciplines (including NET_XMIT_DROP). + * + * Note that regardless of the return value, the skb is consumed + * anyway, so it is currently difficult to retry sending to this + * method. + * */ int __dev_queue_xmit(struct sk_buff *skb, struct net_device *sb_dev) {
When merging net-next for linux-next tree, Stephen Rothwell reported htmldocs warning: Documentation/networking/kapi:92: net/core/dev.c:4101: WARNING: Missing matching underline for section title overline. ----------------------------------------------------------------------------------- I notice this method can also return errors from the queue disciplines, including NET_XMIT_DROP, which is a positive value. So, errors can also The warning is due to comment quote by BLG, which is separated by a dash line above. While it is fine in the docbook days, current documentation framework (Sphinx + kernel-doc) complains about it, so the documentation for __dev_queue_xmit() is not generated. The commit containing the quote is actually d29f749e252bcd ("net: Fix build failure with 'make mandocs'."), which interacts with commit c526fd8f9f4f21 ("net: inline dev_queue_xmit()") that Stephen reported. Fix the warning by removing the quote and adjust the method documentation accordingly. Fixes: d29f749e252bcd ("net: Fix build failure with 'make mandocs'.") Link: https://lore.kernel.org/linux-next/20220503073420.6d3f135d@canb.auug.org.au/ Reported-by: Stephen Rothwell <sfr@canb.auug.org.au> Cc: Dave Jones <davej@redhat.com> Cc: Randy Dunlap <randy.dunlap@oracle.com> Cc: David S. Miller <davem@davemloft.net> Cc: Pavel Begunkov <asml.silence@gmail.com> Cc: netdev@vger.kernel.org Cc: linux-kernel@vger.kernel.org Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com> --- net/core/dev.c | 19 +++++++------------ 1 file changed, 7 insertions(+), 12 deletions(-) base-commit: 0530a683fc858aa641d88ad83315ea53c27bce10