|WARNING| doc: fix API comments for Doxygen 1.18.0

[dpdklab at iol.unh.edu]

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

_AI Code Review_

=== Patch Review: series.patch (via Claude) ===
Review date: 2026-09-03

# DPDK Patch Review

## Summary
This patch fixes Doxygen 1.18.0 compatibility issues by removing parentheses from static function references and degrading struct member references to struct-level links. The changes are documentation-only and appear technically sound, but there are style considerations.

---

## Warnings

### 1. Inconsistent @ref formatting style (Warning)

**Issue:** The patch mixes two different `@ref` formatting approaches for struct members:
- Using quoted member names: `@ref rte_event "flow_id"`
- Using struct-level links with descriptive text in parentheses

**Example from patch:**
```c
/* Mixed style in same file */
- * @ref rte_event.flow_id,
+ * @ref rte_event "flow_id",

/* vs */

- * @ref rte_graph_feature_data_app_cookie_get()
+ * @ref rte_graph_feature_data_app_cookie_get
```

**Why it matters:** While the Doxygen issue forces degradation from member-level to struct-level links, the patch introduces two different conventions for handling this in the same codebase. The eventdev changes use the quoted-name syntax (`rte_event "flow_id"`), while the graph changes simply remove parentheses from function names.

**Suggested approach:** Use a consistent workaround pattern throughout:
- For struct members: either consistently use `@ref structname "membername"` or provide a clear text reference like "the `flow_id` member of @ref rte_event"
- For function references: simply remove the parentheses as done

**Location:**
- `lib/eventdev/rte_eventdev.h`: Uses quoted-name syntax for struct members
- `lib/graph/rte_graph_feature_arc.h`: Only removes parens from function refs (no struct members to compare)

---

### 2. Release notes not updated (Warning)

**Issue:** The patch updates API documentation to work around a Doxygen version incompatibility but does not add a note to the release notes about the documentation changes or the Doxygen version requirement.

**Why it matters:** Users building documentation or maintaining the build environment should know that Doxygen 1.18.0 compatibility has been addressed, and that the documentation format has changed as a workaround for Doxygen issues.

**Suggested fix:** Add a brief note to `doc/guides/rel_notes/release_26_XX.rst` (where XX is the current release) under a "Documentation" or "Known Issues" section mentioning:
- Documentation updated for Doxygen 1.18.0 compatibility
- Some struct member cross-references degraded to struct-level links due to Doxygen limitations

---

### 3. Commit message could be clearer about degradation tradeoff (Info)

**Issue:** The commit message states "degrade the doc by providing a global link to the struct page" but doesn't explain that this is a necessary workaround with no better alternative given the Doxygen regression.

**Current:**
```
The second issue is more difficult and requires to degrade the doc
by providing a global link to the struct page for the fields.
```

**Suggested enhancement:**
```
The second issue has no better workaround and requires degrading the doc
by providing struct-level links instead of member-level links for anonymous
struct/union members.
```

This is informational since the commit message is not subject to AI review per the guidelines.

---

## Info

### Documentation workaround is acceptable

The patch works around two Doxygen regressions:
1. Function references with parentheses broken for static functions
2. Anonymous struct/union member references broken

Both workarounds are reasonable given the Doxygen issues. The removal of parentheses doesn't affect documentation clarity since the function names are still distinctive. The degradation from member-level to struct-level cross-references is unfortunate but unavoidable.

---

## No Issues Found

- **No correctness bugs:** Documentation-only patch, no code changes
- **No resource leaks, use-after-free, or race conditions:** Not applicable (no code)
- **No forbidden tokens:** Not applicable (documentation comments only)
- **No ABI changes:** Documentation-only
- **No test changes needed:** Documentation-only
- **Cc: stable at dpdk.org appropriate:** Yes, documentation fixes for a newer Doxygen version should be backported
- **Code compiles independently:** Yes, documentation changes don't affect compilation

---

## Recommendations

1. **Standardize the struct member reference workaround** across both files for consistency
2. **Add a release note** about Doxygen 1.18.0 compatibility
3. Consider whether the quoted-name syntax (`rte_event "flow_id"`) actually produces useful output in the generated docs, or if plain text references would be clearer to readers

The patch is technically correct and addresses real Doxygen issues. The warnings are about documentation style consistency and process completeness, not correctness.