Clarify option decorator argument wording

[cnaples79]

Summary

• clarify that option decorators accept one or more option names and can optionally specify the function argument name
• explain the common inference pattern for dashed option names mapping to underscored parameter names
• rewrite the basic example description to state the default optional behavior and type

Rationale

• improves docs readability per issue Improve documentation #3175 by fixing confusing grammar and clarifying defaults

Changes

• update docs/options.md with clearer language around argument inference and default option behavior

Tests

• not run (docs-only change)

Fixes #3175

[davidism]

Did you use an LLM tool to make this?

I can kinda see what was attempted here, but if you're saying the original was confusing, this doesn't seem any better, just different. It still feels out of order and doesn't really match the code.

[kdeldycke]

It is safe to consider this PR as superseded by #3192, which has just been merged upstream. Unless the original author is rebasing the changes on top of the new option documentation.