[PATCH net-next] docs: net: page_pool: de-duplicate the intro comment

[PATCH net-next] docs: net: page_pool: de-duplicate the intro comment

[Jakub Kicinski]

In commit 82e896d992fa ("docs: net: page_pool: use kdoc to avoid
duplicating the information") I shied away from using the DOC:
comments when moving to kdoc for documenting page_pool API,
because I wasn't sure how familiar people are with it.

Turns out there is already a DOC: comment for the intro, which
is the same in both places, modulo what looks like minor rewording.
Use the version from Documentation/ but keep the contents with
the code.

Signed-off-by: Jakub Kicinski <kuba@kernel.org>
---
CC: hawk@kernel.org
CC: ilias.apalodimas@linaro.org
CC: corbet@lwn.net
CC: linux-doc@vger.kernel.org
---
 Documentation/networking/page_pool.rst | 18 ++----------------
 include/net/page_pool/helpers.h        | 24 ++++++++++++------------
 2 files changed, 14 insertions(+), 28 deletions(-)

diff --git a/Documentation/networking/page_pool.rst b/Documentation/networking/page_pool.rst
index 68b82cea13e4..215ebc92752c 100644
--- a/Documentation/networking/page_pool.rst
+++ b/Documentation/networking/page_pool.rst
@@ -4,22 +4,8 @@
 Page Pool API
 =============
 
-The page_pool allocator is optimized for the XDP mode that uses one frame
-per-page, but it can fallback on the regular page allocator APIs.
-
-Basic use involves replacing alloc_pages() calls with the
-page_pool_alloc_pages() call.  Drivers should use page_pool_dev_alloc_pages()
-replacing dev_alloc_pages().
-
-API keeps track of in-flight pages, in order to let API user know
-when it is safe to free a page_pool object.  Thus, API users
-must call page_pool_put_page() to free the page, or attach
-the page to a page_pool-aware objects like skbs marked with
-skb_mark_for_recycle().
-
-API user must call page_pool_put_page() once on a page, as it
-will either recycle the page, or in case of refcnt > 1, it will
-release the DMA mapping and in-flight state accounting.
+.. kernel-doc:: include/net/page_pool/helpers.h
+   :doc: page_pool allocator
 
 Architecture overview
 =====================
diff --git a/include/net/page_pool/helpers.h b/include/net/page_pool/helpers.h
index 78df91804c87..94231533a369 100644
--- a/include/net/page_pool/helpers.h
+++ b/include/net/page_pool/helpers.h
@@ -8,23 +8,23 @@
 /**
  * DOC: page_pool allocator
  *
- * This page_pool allocator is optimized for the XDP mode that
- * uses one-frame-per-page, but have fallbacks that act like the
+ * The page_pool allocator is optimized for the XDP mode that
+ * uses one frame per-page, but it can fallback on the
  * regular page allocator APIs.
  *
- * Basic use involve replacing alloc_pages() calls with the
- * page_pool_alloc_pages() call.  Drivers should likely use
+ * Basic use involves replacing alloc_pages() calls with the
+ * page_pool_alloc_pages() call.  Drivers should use
  * page_pool_dev_alloc_pages() replacing dev_alloc_pages().
  *
- * API keeps track of in-flight pages, in-order to let API user know
- * when it is safe to dealloactor page_pool object.  Thus, API users
- * must call page_pool_put_page() where appropriate and only attach
- * the page to a page_pool-aware objects, like skbs marked for recycling.
+ * API keeps track of in-flight pages, in order to let API user know
+ * when it is safe to free a page_pool object.  Thus, API users
+ * must call page_pool_put_page() to free the page, or attach
+ * the page to a page_pool-aware objects like skbs marked with
+ * skb_mark_for_recycle().
  *
- * API user must only call page_pool_put_page() once on a page, as it
- * will either recycle the page, or in case of elevated refcnt, it
- * will release the DMA mapping and in-flight state accounting.  We
- * hope to lift this requirement in the future.
+ * API user must call page_pool_put_page() once on a page, as it
+ * will either recycle the page, or in case of refcnt > 1, it will
+ * release the DMA mapping and in-flight state accounting.
  */
 #ifndef _NET_PAGE_POOL_HELPERS_H
 #define _NET_PAGE_POOL_HELPERS_H
-- 
2.41.0

Re: [PATCH net-next] docs: net: page_pool: de-duplicate the intro comment

[Jesper Dangaard Brouer]

On 07/08/2023 23.00, Jakub Kicinski wrote:
> In commit 82e896d992fa ("docs: net: page_pool: use kdoc to avoid
> duplicating the information") I shied away from using the DOC:
> comments when moving to kdoc for documenting page_pool API,
> because I wasn't sure how familiar people are with it.
> 
> Turns out there is already a DOC: comment for the intro, which
> is the same in both places, modulo what looks like minor rewording.
> Use the version from Documentation/ but keep the contents with
> the code.
> 
> Signed-off-by: Jakub Kicinski <kuba@kernel.org>
> ---
> CC: hawk@kernel.org

Acked-by: Jesper Dangaard Brouer <hawk@kernel.org>


> CC: ilias.apalodimas@linaro.org
> CC: corbet@lwn.net
> CC: linux-doc@vger.kernel.org > ---
>   Documentation/networking/page_pool.rst | 18 ++----------------
>   include/net/page_pool/helpers.h        | 24 ++++++++++++------------
>   2 files changed, 14 insertions(+), 28 deletions(-)
> 
> diff --git a/Documentation/networking/page_pool.rst b/Documentation/networking/page_pool.rst
> index 68b82cea13e4..215ebc92752c 100644
> --- a/Documentation/networking/page_pool.rst
> +++ b/Documentation/networking/page_pool.rst
> @@ -4,22 +4,8 @@
>   Page Pool API
>   =============
>   
> -The page_pool allocator is optimized for the XDP mode that uses one frame
> -per-page, but it can fallback on the regular page allocator APIs.
> -
> -Basic use involves replacing alloc_pages() calls with the
> -page_pool_alloc_pages() call.  Drivers should use page_pool_dev_alloc_pages()
> -replacing dev_alloc_pages().
> -
> -API keeps track of in-flight pages, in order to let API user know
> -when it is safe to free a page_pool object.  Thus, API users
> -must call page_pool_put_page() to free the page, or attach
> -the page to a page_pool-aware objects like skbs marked with
> -skb_mark_for_recycle().
> -
> -API user must call page_pool_put_page() once on a page, as it
> -will either recycle the page, or in case of refcnt > 1, it will
> -release the DMA mapping and in-flight state accounting.
> +.. kernel-doc:: include/net/page_pool/helpers.h
> +   :doc: page_pool allocator
>   
>   Architecture overview
>   =====================
> diff --git a/include/net/page_pool/helpers.h b/include/net/page_pool/helpers.h
> index 78df91804c87..94231533a369 100644
> --- a/include/net/page_pool/helpers.h
> +++ b/include/net/page_pool/helpers.h
> @@ -8,23 +8,23 @@
>   /**
>    * DOC: page_pool allocator
>    *
> - * This page_pool allocator is optimized for the XDP mode that
> - * uses one-frame-per-page, but have fallbacks that act like the
> + * The page_pool allocator is optimized for the XDP mode that
> + * uses one frame per-page, but it can fallback on the
>    * regular page allocator APIs.
>    *
> - * Basic use involve replacing alloc_pages() calls with the
> - * page_pool_alloc_pages() call.  Drivers should likely use
> + * Basic use involves replacing alloc_pages() calls with the
> + * page_pool_alloc_pages() call.  Drivers should use
>    * page_pool_dev_alloc_pages() replacing dev_alloc_pages().
>    *
> - * API keeps track of in-flight pages, in-order to let API user know
> - * when it is safe to dealloactor page_pool object.  Thus, API users
> - * must call page_pool_put_page() where appropriate and only attach
> - * the page to a page_pool-aware objects, like skbs marked for recycling.
> + * API keeps track of in-flight pages, in order to let API user know
> + * when it is safe to free a page_pool object.  Thus, API users
> + * must call page_pool_put_page() to free the page, or attach
> + * the page to a page_pool-aware objects like skbs marked with
> + * skb_mark_for_recycle().
>    *
> - * API user must only call page_pool_put_page() once on a page, as it
> - * will either recycle the page, or in case of elevated refcnt, it
> - * will release the DMA mapping and in-flight state accounting.  We
> - * hope to lift this requirement in the future.
> + * API user must call page_pool_put_page() once on a page, as it
> + * will either recycle the page, or in case of refcnt > 1, it will
> + * release the DMA mapping and in-flight state accounting.
>    */
>   #ifndef _NET_PAGE_POOL_HELPERS_H
>   #define _NET_PAGE_POOL_HELPERS_H

Adjustments looks good to me :-)

--Jesoer

Re: [PATCH net-next] docs: net: page_pool: de-duplicate the intro comment

[patchwork-bot+netdevbpf]

Hello:

This patch was applied to netdev/net-next.git (main)
by Jakub Kicinski <kuba@kernel.org>:

On Mon,  7 Aug 2023 14:00:51 -0700 you wrote:
> In commit 82e896d992fa ("docs: net: page_pool: use kdoc to avoid
> duplicating the information") I shied away from using the DOC:
> comments when moving to kdoc for documenting page_pool API,
> because I wasn't sure how familiar people are with it.
> 
> Turns out there is already a DOC: comment for the intro, which
> is the same in both places, modulo what looks like minor rewording.
> Use the version from Documentation/ but keep the contents with
> the code.
> 
> [...]

Here is the summary with links:
  - [net-next] docs: net: page_pool: de-duplicate the intro comment
    https://git.kernel.org/netdev/net-next/c/2c2b88748fd5

You are awesome, thank you!
-- 
Deet-doot-dot, I am a bot.
https://korg.docs.kernel.org/patchwork/pwbot.html