|SUCCESS| [v3] 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/166738

_AI Code Review_

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

# DPDK Patch Review

## Summary

This documentation clarification patch is **correct** and improves the API documentation for `rte_dma_completed()` and `rte_dma_completed_status()`. No correctness bugs or style violations were found.

---

## Detailed Review

### Correctness: PASS

No correctness issues identified. The patch modifies only documentation (comments in a header file) and does not change any code logic or data structures.

### C Coding Style: PASS

- **Formatting**: All changes are within comment blocks; no code formatting issues apply.
- **Comment style**: Multi-line comments use the correct DPDK format (`/* ... */` with proper indentation).
- **Line length**: All lines are within acceptable limits.
- **No forbidden tokens**: No code changes, so no token usage issues.

### API and Documentation Requirements: PASS

- **Documentation matches code behavior**: The clarified documentation accurately describes the existing API semantics without changing the API itself.
- **No ABI changes**: Header-only documentation update; no symbol changes.
- **Release notes**: Not required for documentation-only clarification fixes.
- **Fixes tag present**: Correctly references the original commit that introduced the ambiguous documentation.

### Specific Documentation Improvements

The patch successfully addresses the ambiguity between the two completion APIs:

1. **`rte_dma_completed()`**: Now explicitly states it reports only successful operations and stops at the first error.

2. **`rte_dma_completed_status()`**: Now explicitly states it reports all completed operations regardless of status.

3. **`last_idx` clarification**: Both functions now clearly explain that `last_idx` refers to the last **reported** operation (bounded by `nb_cpls`), which may not be the last operation the device has actually completed. This is an important distinction.

4. **`has_error` clarification**: The enhanced description for `rte_dma_completed()` now explains both the true and false cases, making the stopping behavior explicit.

5. **`status` array clarification**: `rte_dma_completed_status()` now explicitly states that if `n` operations are returned, the first `n` entries in the status array are valid.

---

## Conclusion

**No issues found.** The patch improves documentation clarity without introducing any technical problems. The changes are well-structured and align with DPDK documentation standards.