|WARNING| 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/166734

_AI Code Review_

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

# DPDK Patch Review

## Summary
This patch clarifies documentation for the `last_idx` parameter in two DMA completion APIs. The changes are documentation-only and improve clarity about the different semantics of `rte_dma_completed()` vs `rte_dma_completed_status()`.

---

## Findings

### **Errors**
None.

### **Warnings**
None.

### **Info**

**Documentation clarity** (Info)

The clarification is helpful, but consider making the distinction even more explicit in both descriptions:

For `rte_dma_completed()` (line 1341):
```c
 * @param[out] last_idx
- *   The last successfully completed operation's ring_idx.
+ *   The last successfully completed operation's ring_idx. This function stops
+ *   at the first error, so last_idx points to the last success before any error.
 *   If not required, NULL can be passed in.
```

For `rte_dma_completed_status()` (line 1399-1401):
The current wording is good but could emphasize the contrast:
```c
 * @param[out] last_idx
 *   The last completed operation's ring_idx, regardless of whether it
- *   completed successfully or with an error.
+ *   completed successfully or with an error. Unlike rte_dma_completed(),
+ *   this function processes all completed operations including errors.
 *   If not required, NULL can be passed in.
```

This would make the API contract clearer for developers choosing between the two functions.

---

## Conclusion

The patch is **correct and acceptable**. It improves API documentation clarity without changing code behavior. The optional suggestions above would further strengthen the documentation but are not required for approval.
Traceback (most recent call last):
  File "/home-local/jenkins-local/jenkins-agent/workspace/AI-Code-Review/dpdk/devtools/ai/review-patch.py", line 1358, in <module>
    main()
  File "/home-local/jenkins-local/jenkins-agent/workspace/AI-Code-Review/dpdk/devtools/ai/review-patch.py", line 1354, in main
    sys.exit(classify_review(review_text, args.output_format))
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home-local/jenkins-local/jenkins-agent/workspace/AI-Code-Review/dpdk/devtools/ai/review-patch.py", line 180, in classify_review
    elif curr_state == ReviewParseState.IN_ERROR and not re.match(
         ^^^^^^^^^^
UnboundLocalError: cannot access local variable 'curr_state' where it is not associated with a value