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

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

[Bagas Sanjaya]

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()").

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@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 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@gmail.com/
 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
-- 
An old man doll... just what I always wanted! - Clara

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@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 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@gmail.com/
>  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

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

[Jakub Kicinski]

On Thu,  5 May 2022 15:29:07 +0700 Bagas Sanjaya wrote:
>   *	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

Rephrase the text as a normal function documentation and drop 
the banner and the signature, please.

The place to give people credit for providing the information 
is the git logs. So you can say something like:

  Rephrase the quote from Ben Greear (BLG) as a normal kdoc.

in the commit message.