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

[dpdklab at iol.unh.edu]

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

_AI Code Review_

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

85f3a9dea3c1 ("ring: fix zero-copy burst API documentation")
Author: Zhiguang Jin <jinzhiguang at kylinos.cn>
Subject: ring: fix zero-copy burst API documentation

This patch updates documentation for four zero-copy burst API functions
in the ring library to accurately reflect that they return the actual
number of objects processed, rather than "either 0 or n".

> diff --git a/.mailmap b/.mailmap
> index 4d26d9c286..3172cb08e3 100644
> --- a/.mailmap
> +++ b/.mailmap
> @@ -1934,6 +1934,7 @@ Zhichao Zeng <zhichaox.zeng at intel.com>
>  Zhigang Hu <zhigang.hu at intel.com>
>  Zhigang Lu <zlu at ezchip.com>
>  Zhiguang He <hezhiguang3 at huawei.com>
> +Zhiguang Jin <jinzhiguang at kylinos.cn>
>  Zhihong Peng <zhihongx.peng at intel.com>
>  Zhihong Wang <wangzhihong.wzh at bytedance.com> <zhihong.wang at intel.com>
>  Zhike Wang <wangzk at jd.com> <wangzk320 at 163.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.
>   */
>  static __rte_always_inline unsigned int
>  rte_ring_enqueue_zc_burst_elem_start(struct rte_ring *r, unsigned int esize,

The documentation states "The actual number of objects that can be
enqueued" but doesn't specify the range. Looking at the function
implementation, does it call __rte_ring_do_enqueue_zc_elem_start() with
behavior RTE_RING_QUEUE_VARIABLE? If so, should the documentation
explicitly state the return value range is [0, n] for clarity, similar
to other burst API documentation in DPDK?

> @@ -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 applies here - should the documentation include the range
[0, n] to make the best-effort behavior explicit?

> @@ -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.
>   */

For consistency with typical DPDK burst API documentation patterns,
should this also specify the [0, n] range explicitly?

> @@ -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 consistency question - would explicitly stating [0, n] improve
clarity here as well?