linux-kernel - [PATCH net-next] net/core: Remove comment quote for __dev_queue

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [thread-next>] [day] [month] [year] [list]

Date:   Tue,  3 May 2022 14:29:49 +0700
From:   Bagas Sanjaya <bagasdotme@...il.com>
To:     linux-doc@...r.kernel.org
Cc:     Bagas Sanjaya <bagasdotme@...il.com>,
        Stephen Rothwell <sfr@...b.auug.org.au>,
        Dave Jones <davej@...hat.com>,
        Randy Dunlap <randy.dunlap@...cle.com>,
        "David S . Miller" <davem@...emloft.net>,
        Pavel Begunkov <asml.silence@...il.com>,
        netdev@...r.kernel.org, linux-kernel@...r.kernel.org
Subject: [PATCH net-next] 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'.")
Link: https://lore.kernel.org/linux-next/20220503073420.6d3f135d@canb.auug.org.au/
Reported-by: Stephen Rothwell <sfr@...b.auug.org.au>
Cc: Dave Jones <davej@...hat.com>
Cc: Randy Dunlap <randy.dunlap@...cle.com>
Cc: David S. Miller <davem@...emloft.net>
Cc: Pavel Begunkov <asml.silence@...il.com>
Cc: netdev@...r.kernel.org
Cc: linux-kernel@...r.kernel.org
Signed-off-by: Bagas Sanjaya <bagasdotme@...il.com>
---
 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