feat: Experimental annotated argparse

[KelvinChung2000]

Adds @with_annotated, a type-hint-driven alternative to @with_argparser that builds the parser automatically from a command's signature (positional/option inference, enum/literal/path/collection handling, subcommands, groups, mutex). Marked experimental.

• New module cmd2/annotated.py plus Argument / Option metadata classes exported from cmd2
• Underscored param names auto-dasherize in generated flags (dry_run → --dry-run); opt out via Option("--my_flag")
• Dedicated docs page docs/features/annotated.md with an experimental admonition; argument_processing.md keeps a short pointer
• Example app examples/annotated_example.py and test suite in tests/test_annotated.py

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.54%. Comparing base (e2c061c) to head (a4db7ce).

Additional details and impacted files

@@           Coverage Diff            @@
##             main    #1666    +/-   ##
========================================
  Coverage   99.53%   99.54%            
========================================
  Files          22       23     +1     
  Lines        4928     5680   +752     
========================================
+ Hits         4905     5654   +749     
- Misses         23       26     +3     

Flag	Coverage Δ
unittests	99.54% <100.00%> (+<0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[tleonhardt]

I plan to review this PR this weekend. @kmvanbrunt @bambu I'd very much appreciate your feedback as well.

[kmvanbrunt]

@KelvinChung2000

How can I do the following?

1. Set the title and description for an argument group?
2. Set the description and epilog for a parser?
3. Set a custom help formatter class for a parser?
4. Use a custom parser class?

[KelvinChung2000]

I have updated the implementation to be as declarative as possible. So, in terms of maintenance or edge cases, you can add/ban them by just adding a new rule.

Hopefully, I have now covered most of the missing features.

[KelvinChung2000]

Actually, do you want me to split the mega file and store it under something like cmd2/annotated? I can move out some of the "noise" like changes to potentially make things easier to review. This sort of large diff commit, GitHub is just not that well designed for it.

[tleonhardt]

@KelvinChung2000 I'm flexible. I can see an argument for keeping it all self-contained within one file.

But I could also see the argument for splitting it into multiple files underneath the cmd2.annotated namespace - basically into its own sub-package.

@kmvanbrunt Would you have a preference here?

[tleonhardt]

@KelvinChung2000 I chatted with @kmvanbrunt - for now please leave everything in the one big file annotated.py. Later if things grow, we can consider breaking up into multiple files.

[tleonhardt]

@KelvinChung2000 I pushed a change to add @with_annotated to the top level namespace after chatting with @kmvanbrunt about it.

I also pushed a fix for the minor edge case bug I mentioned last time.

From my perspective, this is good to merge. If anyone has any further comments or recommendations, put them forth sooner rather than later. I'll merge this a day or two from now if there are no further suggestions.