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/[email protected]/
Reported-by: Stephen Rothwell <[email protected]>
Cc: Dave Jones <[email protected]>
Cc: Randy Dunlap <[email protected]>
Cc: David S. Miller <[email protected]>
Cc: Pavel Begunkov <[email protected]>
Cc: [email protected]
Cc: [email protected]
Signed-off-by: Bagas Sanjaya <[email protected]>
---
net/core/dev.c | 19 +++++++------------
1 file changed, 7 insertions(+), 12 deletions(-)
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)
{
base-commit: 0530a683fc858aa641d88ad83315ea53c27bce10
--
An old man doll... just what I always wanted! - Clara
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.
--
An old man doll... just what I always wanted! - Clara
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.
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 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?
[+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/[email protected]/#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.
>