Subject: Re: [PATCH net-next v2] net/core: use ReST block quote in __dev_queue_xmit() comment

From: Akira Yokosawa <[email-masked]>
Date: Thu, 5 May 2022 19:42:26 +0900

On 2022/05/05 17:29,
Bagas Sanjaya wrote:
> 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 Ben from commit af191367a75262
> ("[NET]: Document ->hard_start_xmit() locking in comments.") interacts
> with commit c526fd8f9f4f21 ("net: inline dev_queue_xmit()").

I don't see why the change in commit c526fd8f9f4f21 caused the new
warning.
Please explain.  Just saying "interacts with" does not explain
anything.

        Thanks, Akria

> 
> Fix the warning by using ReST block quote syntax for the comment quote.
> Note that the actual description for the method will be rendered above
> "Description" section instead of below of it. However, preserve the
> comment quote for now.
> 
> Fixes: c526fd8f9f4f21 ("net: inline dev_queue_xmit()")
> Link: https://lore.kernel.org/linux-next/[email-masked]/
> Reported-by: Stephen Rothwell <[email-masked]>
> Cc: Ben Greear <[email-masked]>
> Cc: Pavel Begunkov <[email-masked]>
> Cc: "David S. Miller" <[email-masked]>
> Cc: Jakub Kicinski <[email-masked]>
> Cc: Akira Yokosawa <[email-masked]>
> Cc: [email-masked]
> Cc: [email-masked]
> Cc: [email-masked]
> Signed-off-by: Bagas Sanjaya <[email-masked]>
> ---
>  Changes since v1 [1]:
>    - Use ReST block quote instead of deleting the comment quote
>    - Mention the originating commit that introduces the quote
> 
>  [1]: https://lore.kernel.org/linux-doc/[email-masked]/
>  net/core/dev.c | 19 ++++++++++---------
>  1 file changed, 10 insertions(+), 9 deletions(-)
> 
> diff --git a/net/core/dev.c b/net/core/dev.c
> index c2d73595a7c369..bcb47b889f5857 100644
> --- a/net/core/dev.c
> +++ b/net/core/dev.c
> @@ -4099,17 +4099,18 @@ struct netdev_queue *netdev_core_pick_tx(struct net_device *dev,
>   *	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.)
> + *        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.
>   *
> - *      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
> + *        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
>   */
>  int __dev_queue_xmit(struct sk_buff *skb, struct net_device *sb_dev)
>  {
> 
> base-commit: 4950b6990e3b1efae64a5f6fc5738d25e3b816b3