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

* [PATCH net-next v3] net/core: Rephrase function description of __dev_queue_xmit()
@ 2022-05-07  8:46 Bagas Sanjaya
  2022-05-08 11:48 ` Akira Yokosawa
  0 siblings, 1 reply; 5+ messages in thread
From: Bagas Sanjaya @ 2022-05-07  8:46 UTC (permalink / raw)
  To: linux-doc
  Cc: Bagas Sanjaya, Stephen Rothwell, Ben Greear, Pavel Begunkov,
	David S. Miller, Jakub Kicinski, Akira Yokosawa, netdev,
	linux-next, linux-kernel

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:

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

Fix the warning by rephrasing the function description. This is done by
incorporating notes from the quote as well as dropping the banner and
attribution signature.

Fixes: c526fd8f9f4f21 ("net: inline dev_queue_xmit()")
Link: https://lore.kernel.org/linux-next/20220503073420.6d3f135d@canb.auug.org.au/
Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
Cc: Ben Greear <greearb@candelatech.com>
Cc: Pavel Begunkov <asml.silence@gmail.com>
Cc: "David S. Miller" <davem@davemloft.net>
Cc: Jakub Kicinski <kuba@kernel.org>
Cc: Akira Yokosawa <akiyks@gmail.com>
Cc: netdev@vger.kernel.org
Cc: linux-next@vger.kernel.org
Cc: linux-kernel@vger.kernel.org
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Changes since v2 [1]:
   - Approach the problem by rephrasing (suggested by Jakub)
   - Explain that inlining in the Fixes: commit triggers the warning
     (suggested by Akira)

 [1]: https://lore.kernel.org/linux-doc/20220505082907.42393-1-bagasdotme@gmail.com/

 net/core/dev.c | 30 ++++++++++++++----------------
 1 file changed, 14 insertions(+), 16 deletions(-)

diff --git a/net/core/dev.c b/net/core/dev.c
index f036ccb61da4da..75c00bb45f9b46 100644
--- a/net/core/dev.c
+++ b/net/core/dev.c
@@ -4139,22 +4139,20 @@ struct netdev_queue *netdev_core_pick_tx(struct net_device *dev,
  *	have set the device and priority and built the buffer before calling
  *	this function. The function can be called from an interrupt.
  *
- *	A negative errno code is returned on a failure. A success does not
- *	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 function can returns a negative errno code in case of failure.
+ *	Positive errno code can also be returned from the queue disciplines
+ *	(including NET_XMIT_DROP). A success does not guarantee the frame
+ *	will be transmitted as it may be dropped due to congestion or
+ *	traffic shaping.
+ *
+ *	The skb is consumed anyway regardless of return value, so it is
+ *	currently difficult to retry sending to this method. If careful,
+ *	you can bump the ref count before sending to hold a reference for
+ *	retry.
+ *
+ *	Interrupts must be enabled when calling this function, because
+ *	BH-enabled code must have IRQs enabled so that it will not deadlock.
+ *
  */
 int __dev_queue_xmit(struct sk_buff *skb, struct net_device *sb_dev)
 {

base-commit: 8fc0b6992a06998404321f26a57ea54522659b64
-- 
An old man doll... just what I always wanted! - Clara


^ permalink raw reply related	[flat|nested] 5+ messages in thread