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

[dpdklab at iol.unh.edu]

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

_AI Code Review_

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

# Review of DPDK Patch: dmadev last_idx Documentation Clarification

## Summary
This patch clarifies documentation for the `last_idx` output parameter in `rte_dma_completed()` and `rte_dma_completed_status()`. The changes are documentation-only and accurately describe the semantic differences between the two APIs.

---

## Findings

### **Errors**
None.

### **Warnings**
None.

### **Info**

**Documentation style - grammatical improvement:**

In both modified parameter descriptions, the phrase "this may not be the last operation the device has actually completed" would be clearer as "this may not be the ring_idx of the last operation the device has actually completed" for parallel structure with the first part of the sentence.

Current (line 1341-1342):
```
The ring_idx of the last successfully completed operation reported by
this call (at most nb_cpls operations are reported, so this may not be
the last operation the device has actually completed).
```

Suggested:
```
The ring_idx of the last successfully completed operation reported by
this call (at most nb_cpls operations are reported, so this may not be
the ring_idx of the last operation the device has actually completed).
```

Similarly for line 1402-1404.

This maintains consistent subject-verb agreement ("ring_idx ... may not be the ring_idx").

---

## Conclusion

The patch correctly clarifies the semantic difference between the two completion APIs:
- `rte_dma_completed()`: reports only successful completions, stops at first error
- `rte_dma_completed_status()`: reports all completions regardless of status

Both descriptions now explicitly state the `nb_cpls` bound and that `last_idx` refers to the last *reported* operation, not necessarily the last completed by hardware.

The code changes are documentation-only, require no functional testing, and appropriately target the Fixes tag for a documentation ambiguity. No release notes are required for documentation-only clarifications.

**Recommendation:** Accept with optional grammatical refinement noted above.