|SUCCESS| [v3] ring: fix zero-copy burst API documentation

[dpdklab at iol.unh.edu]

Test-Label: ai-code-review
Test-Status: SUCCESS
https://dpdk.org/patch/164138

_AI Code Review_

=== Patch Review: series.patch (via Claude) ===
Review date: 2026-05-19

I'll review this patch for correctness bugs, coding style compliance, and adherence to DPDK guidelines.

git sha: 3df2b104538811f1aa26b74ffac11d73
Author: jinzhiguang <jinzhiguang at kylinos.cn>
Subject: [PATCH v3] ring: fix zero-copy burst API documentation

Brief summary: This patch corrects the documentation of zero-copy burst APIs
in rte_ring_peek_zc.h to indicate they return the actual number of objects
that can be enqueued/dequeued (0 to n) rather than claiming they return
"either 0 or n".

> diff --git a/.mailmap b/.mailmap
> index 4d26d9c286..a4f91f2131 100644
> --- a/.mailmap
> +++ b/.mailmap
> @@ -756,6 +756,7 @@ Jing Chen <jing.d.chen at intel.com>
>  Jingguo Fu <jingguox.fu at intel.com>
>  Jingjing Wu <jingjing.wu at intel.com>
>  Jingzhao Ni <jingzhao.ni at arm.com>
> +jinzhiguang <jinzhiguang at kylinos.cn>
>  Jiri Slaby <jslaby at suse.cz>
>  Job Abraham <job.abraham at intel.com>
>  Jochen Behrens <jochen.behrens at broadcom.com> <jbehrens at vmware.com>

[ ... ]

> diff --git a/lib/ring/rte_ring_peek_zc.h b/lib/ring/rte_ring_peek_zc.h
> index 3254fe0481..43d6a53075 100644
> --- a/lib/ring/rte_ring_peek_zc.h
> +++ b/lib/ring/rte_ring_peek_zc.h
> @@ -235,7 +235,7 @@ rte_ring_enqueue_zc_bulk_start(struct rte_ring *r, unsigned int n,
>   *   If non-NULL, returns the amount of space in the ring after the
>   *   reservation operation has finished.
>   * @return
> - *   The number of objects that can be enqueued, either 0 or n
> + *   The actual number of objects that can be enqueued.
>   */

Does the new description adequately explain the return value range? The
original text mentioned "either 0 or n", which was incorrect for burst
APIs. However, the new text lacks specificity about the range (0 to n).
Consider whether "The actual number of objects that can be enqueued,
between 0 and n" would be clearer and more consistent with other DPDK API
documentation.

>  static __rte_always_inline unsigned int
>  rte_ring_enqueue_zc_burst_elem_start(struct rte_ring *r, unsigned int esize,
> @@ -265,7 +265,7 @@ rte_ring_enqueue_zc_burst_elem_start(struct rte_ring *r, unsigned int esize,
>   *   If non-NULL, returns the amount of space in the ring after the
>   *   reservation operation has finished.
>   * @return
> - *   The number of objects that can be enqueued, either 0 or n.
> + *   The actual number of objects that can be enqueued.
>   */

Same question about explicitness of range applies to
rte_ring_enqueue_zc_burst_start() here.

[ ... ]

> @@ -442,7 +442,7 @@ rte_ring_dequeue_zc_bulk_start(struct rte_ring *r, unsigned int n,
>   *   If non-NULL, returns the number of remaining ring entries after the
>   *   dequeue has finished.
>   * @return
> - *   The number of objects that can be dequeued, either 0 or n.
> + *   The actual number of objects that can be dequeued.
>   */

Same question about range specificity applies to
rte_ring_dequeue_zc_burst_elem_start().

[ ... ]

> @@ -471,7 +471,7 @@ rte_ring_dequeue_zc_burst_elem_start(struct rte_ring *r, unsigned int esize,
>   *   If non-NULL, returns the number of remaining ring entries after the
>   *   dequeue has finished.
>   * @return
> - *   The number of objects that can be dequeued, either 0 or n.
> + *   The actual number of objects that can be dequeued.
>   */

Same question about range specificity applies to
rte_ring_dequeue_zc_burst_start().

The patch correctly fixes the documentation issue. However, for
consistency with DPDK API documentation style and to provide more
complete information to users, consider explicitly stating the return
value range as "between 0 and n" or "in the range [0, n]" rather than
just "actual number". This would match the style typically used in other
DPDK ring API documentation.