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
