Skip to contentSkip to conversation

net/core: Remove comment quote for __dev_queue_xmit()

PATCH In review Bagas Sanjaya 3 participants 6 messages May 3, 2022 – May 5, 2022

Subsystems (3)
lore
Share & tools
lore
#0 lore raw

PATCH 1/1 net/core: Remove comment quote for __dev_queue_xmit()

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'.")
Cc Dave Jones <[email protected]>
Cc Randy Dunlap <[email protected]>
Cc David S. Miller <[email protected]>
Cc Pavel Begunkov <[email protected]>
---
 net/core/dev.c | 19 +++++++------------
 1 file changed, 7 insertions(+), 12 deletions(-)
net/core/dev.c +7 -12
index d127164771f222..b5273f820ca840 100644
@@ -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)
 {

base-commit: 0530a683fc858aa641d88ad83315ea53c27bce10

Signature · 1 line
An old man doll... just what I always wanted! - Clara
maintainer
#1 lore raw
Quoted 8 lines · 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.)
Quoted 10 lines

- *
- * 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?

#2 lore raw
Quoted 20 lines · Jakub Kicinski
Quoted 8 lines · 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.)
Quoted 10 lines

- *
- * 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.

Quoted 2 lines

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.

Signature · 1 line
An old man doll... just what I always wanted! - Clara
#3 lore raw

Hi,

Quoted 1 line · Bagas Sanjaya

On 5/4/22 08:03, Jakub Kicinski wrote:

[...]

Quoted 5 lines
Quoted 2 lines

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

Quoted 2 lines

Actually the "--BLG" signature is the culprit.

maintainer
#4 lore raw
Quoted 2 lines · On Wed, 4 May 2022 22:43:12 +0900 Akira Yokosawa wrote:
Quoted 2 lines

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.

Quoted 7 lines

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.

Quoted 1 line
Quoted 1 line

Actually the "--BLG" signature is the culprit.

#5 lore raw

[+To: Ben]
[-Cc: unreachable addresses]

Hi,

Quoted 9 lines · Jakub Kicinski
Quoted 2 lines · On Wed, 4 May 2022 22:43:12 +0900 Akira Yokosawa wrote:
Quoted 2 lines

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.

Quoted 2 lines

Actually, it is possible.

Quoted 7 lines
Quoted 5 lines

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/[email protected]/#r
Quoted 3 lines

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

Quoted 3 lines
Quoted 2 lines
Quoted 2 lines

Actually the "--BLG" signature is the culprit.