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

[Akira Yokosawa]

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/20220503073420.6d3f135d@xxxxxxxxxxxxxxxx/
> Reported-by: Stephen Rothwell <sfr@xxxxxxxxxxxxxxxx>
> Cc: Ben Greear <greearb@xxxxxxxxxxxxxxx>
> Cc: Pavel Begunkov <asml.silence@xxxxxxxxx>
> Cc: "David S. Miller" <davem@xxxxxxxxxxxxx>
> Cc: Jakub Kicinski <kuba@xxxxxxxxxx>
> Cc: Akira Yokosawa <akiyks@xxxxxxxxx>
> Cc: netdev@xxxxxxxxxxxxxxx
> Cc: linux-next@xxxxxxxxxxxxxxx
> Cc: linux-kernel@xxxxxxxxxxxxxxx
> Signed-off-by: Bagas Sanjaya <bagasdotme@xxxxxxxxx>
> ---
>  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/20220503072949.27336-1-bagasdotme@xxxxxxxxx/
>  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