|WARNING| [v2] dmadev: clarify last_idx documentation for completion APIs

[dpdklab at iol.unh.edu]

Test-Label: ai-code-review
Test-Status: WARNING
https://dpdk.org/patch/166735

_AI Code Review_

=== Patch Review: series.patch (via Claude) ===
Review date: 2026-07-15

# DPDK Patch Review

## Summary

This is a documentation-only patch that clarifies the `last_idx` parameter semantics in the dmadev completion APIs. The changes are well-motivated and technically correct.

---

## Findings

### Errors

None.

### Warnings

**Warning: Release notes missing for API documentation clarification**

The patch fixes ambiguous API documentation that could lead to incorrect usage (treating `last_idx` from `rte_dma_completed()` as if it were from `rte_dma_completed_status()` or vice versa). This is a user-facing clarification that should be documented in release notes under "API Changes" or "Documentation Updates" for the current release.

Add an entry to `doc/guides/rel_notes/release_26_07.rst` (or the appropriate release file) explaining that the `last_idx` parameter documentation has been clarified to distinguish between the two completion APIs.

---

## Info

**Info: Documentation style is clear**

The rewording successfully disambiguates the two APIs:
- `rte_dma_completed()`: "last successfully completed operation reported"
- `rte_dma_completed_status()`: "last operation reported... regardless of... success or error"

The parenthetical note about `nb_cpls` bounding is helpful and applies to both functions consistently.

---

## Overall Assessment

The patch correctly addresses a documentation ambiguity. The only actionable item is adding a release note entry since this clarifies API behavior that applications depend on.