Improve Rustdoc examples for public and test-support APIs

[lodyai]

Finding

Public API documentation is present in many places, but example coverage is uneven relative to the repository guidance that function documentation should include clear usage examples.

High-volume areas from the audit:

• src/status.rs
• src/stdlib/config.rs
• src/cli/parser.rs
• src/theme.rs
• src/runner/mod.rs
• src/ast.rs
• test_support/src/env.rs
• test_support/src/env_guard.rs

The audit also found missing Rustdoc on several public or crate-visible helpers, including runner process file I/O helpers and glob helper methods.

Why This Matters

The crate enables strict docs linting, but the project standard is stronger than “has some docs”. Missing examples make public APIs harder to use correctly and reduce doctest value.

Proposed Fix

Add realistic # Examples sections to the highest-use public APIs first, then work through remaining public and reusable test-support APIs. Add missing /// comments for public helper methods and type aliases found during the audit.

Acceptance Criteria

• Highest-use public APIs listed above have examples or a documented reason why an example would be misleading.
• Missing Rustdoc on public runner/glob helpers is filled in.
• New examples compile or are explicitly marked no_run/ignore with a reason.
• make check-fmt, make lint, and make test pass.

[coderabbitai]

🔗 Related PRs

leynos/dear-diary#28 - Add Whitaker to lint checks [merged]
leynos/memoryd#3 - Record evidence-store engine policy (1.1.1) [merged]
leynos/stilyagi#20 - Refresh agent documentation standards [merged]
leynos/rstest-bdd#502 - E0499/E0502 troubleshooting entry (10.2.2) [merged]
leynos/rstest-bdd#521 - docs: make users-guide links portable outside the repo tree (#499) [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!