|SUCCESS| devtools: add script to find orphan documentation files

[dpdklab at iol.unh.edu]

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

_AI Code Review_

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

# DPDK Patch Review: devtools/check-doc-orphans.py

## Summary

This patch adds a Python script to detect orphaned documentation files. The code is well-structured and follows good practices. No correctness bugs or critical issues were found.

## Findings

### **Info** - Style and Minor Suggestions

1. **Line 96: URL scheme check could be more robust**
   ```python
   if not target or target.startswith(("http:", "https:", "mailto:")):
   ```
   Consider adding `"ftp:"` and `"file:"` schemes if those are valid in DPDK documentation.
   Not a bug - current check is sufficient for typical use.

2. **Line 76: Exception handling is correct**
   ```python
   except OSError as err:
       sys.exit(f"{path}: {err.strerror}")
   ```
   This is appropriate for a standalone script. No changes needed.

3. **Line 140: Loop performance**
   The `next()` call with generator expression on line 143 searches through `path.parents` on every iteration. For deeply nested paths this could be optimized by pre-computing a mapping, but the performance impact is negligible for documentation scanning.

4. **Line 201: Return value construction**
   ```python
   return 1 if unused or (args.missing and missing) else 0
   ```
   Clear and correct. The non-zero return on errors allows CI integration as stated in the commit message.

### **Pass** - Python Style Compliance

The script follows Python conventions:
- 4-space indentation (required for Python in DPDK)
- Lines under 100 characters
- Type hints could be added to function signatures for better clarity, but are not required
- Docstrings are present and descriptive

### **Pass** - Functional Correctness

- **No resource leaks**: Files are opened via `read_text()` which handles closing automatically
- **Error handling**: File read errors are caught and reported with `sys.exit()`
- **Path handling**: Uses `pathlib.Path.resolve()` to normalize paths, avoiding symlink issues
- **Regex patterns**: Well-formed, no ReDoS vulnerabilities (no nested quantifiers)
- **Graph traversal**: Correctly implements BFS with a `seen` set to avoid infinite loops

### **Pass** - Documentation Requirements

- Script has a module-level docstring explaining its purpose
- Functions have docstrings describing their behavior
- Command-line help text (`argparse`) provides usage information
- Release notes are not required for devtools scripts

### **Pass** - DPDK Process Compliance

- SPDX license identifier present (BSD-3-Clause)
- Copyright notice present (2026 Stephen Hemminger)
- Script is executable helper tool, not part of core DPDK libraries
- No ABI/API implications
- No experimental API usage

## Conclusion

**No errors or warnings.** The patch is well-written and ready for integration. The script provides useful functionality for maintaining documentation hygiene and integrates properly with CI through its exit status.