docs: clarify C901 complexity example

[ya-nsh]

Summary

• clarifies the C901 documentation example so the before/after guidance does not imply that guard clauses necessarily reduce McCabe complexity
• replaces the previous nested-vs-guard-clause example with an example that moves decision-making into a focused helper

Fixes #25028.

Validation

• git diff --check
• sanity-checked the edited docs block with a short Python script

Note: I attempted the repository preflight command uvx prek run -a, but this environment does not have the Rust toolchain installed, so the rustfmt hook failed before running:

error: Failed to run hook `rustfmt`
  caused by: Run command `run system command` failed
  caused by: No such file or directory (os error 2)

This change only updates Rust doc comments for the generated rule documentation.

[ntBre]

Thanks! I think this is a little better, but it feels a bit outside the spirit of the rule to me just to move the complexity into a helper function (which would actually make reading/reviewing the code more complex, in my opinion). Codex suggested something like the following, where we replace a sequence of if conditions with a dict lookup:

# Before: branch-heavy lookup
def normalize_status(status):
    if status == "new":
        return "queued"
    if status == "queued":
        return "running"
    if status == "running":
        return "done"
    if status == "failed":
        return "retry"
    if status == "cancelled":
        return "closed"
    return "unknown"


# After: the decision table is data, not control flow
STATUS_TRANSITIONS = {
    "new": "queued",
    "queued": "running",
    "running": "done",
    "failed": "retry",
    "cancelled": "closed",
}


def normalize_status_lookup(status):
    return STATUS_TRANSITIONS.get(status, "unknown")

That specifically is pretty verbose, but I kind of like something in that direction.

I also realized that the default value of max-complexity is 10, so neither the existing nor new input examples actually trigger C901 out of the box. I don't think we need to extend the length of the examples to meet that level of complexity, but we should probably note that somewhere (e.g. "These examples assume a lint.mccabe.max-complexity of ..."). I'll try to remember to comment on #18972 to mark this rule as an exception, assuming we go that route.

[ya-nsh]

Addressed in 3acd130: updated the C901 docs example to use the lookup-table direction you suggested and explicitly notes that the example assumes a max complexity of 5.

Validation: git diff --check- Parsed both Python snippets and confirmed the before example has complexity 6 while the lookup-table version has complexity 1

I also reran uvx prek run -a, but it still cannot complete in this environment because the rustfmt hook fails with No such file or directory.