chore: move documentation

Author: KelvinChung2000

docs/features/annotated.md

@@ -0,0 +1,247 @@
+# Annotated Argument Processing
+
+!!! warning "Experimental"
+
+    The `@with_annotated` decorator and its supporting `Argument` / `Option` metadata classes are
+    **experimental**. The public API, the surface of accepted type annotations, and the generated
+    argparse behavior may all change in future releases without a deprecation cycle. Pin a specific
+    `cmd2` version if you depend on the exact current semantics, and expect to revisit your usage on
+    upgrades.
+
+    For production code that needs stable behavior, use
+    [@with_argparser](argument_processing.md#with_argparser-decorator) instead.
+
+The [@with_annotated][cmd2.decorators.with_annotated] decorator builds an argparse parser
+automatically from the decorated function's type annotations. No manual `add_argument()` calls are
+required, and the command body receives typed keyword arguments directly instead of an
+`argparse.Namespace`.
+
+The two decorators are interchangeable -- here is the same command written both ways:
+
+=== "@with_annotated"
+
+    ```py
+    @with_annotated
+    def do_greet(self, name: str, count: int = 1, loud: bool = False):
+        for _ in range(count):
+            msg = f"Hello {name}"
+            self.poutput(msg.upper() if loud else msg)
+    ```
+
+=== "@with_argparser"
+
+    ```py
+    parser = Cmd2ArgumentParser()
+    parser.add_argument('name', help='person to greet')
+    parser.add_argument('--count', type=int, default=1, help='repetitions')
+    parser.add_argument('--loud', action='store_true', help='shout')
+
+    @with_argparser(parser)
+    def do_greet(self, args):
+        for _ in range(args.count):
+            msg = f"Hello {args.name}"
+            self.poutput(msg.upper() if args.loud else msg)
+    ```
+
+The annotated version is more concise, gives you typed parameters, and supports several advanced
+cmd2 features directly, including `ns_provider`, `with_unknown_args`, and typed subcommands. Pick
+`@with_argparser` when you need a stable, well-established API or fine-grained control over the
+parser; pick `@with_annotated` when you want type-hint-driven ergonomics and can accept the
+experimental status.
+
+## Basic usage
+
+Parameters without defaults become positional arguments. Parameters with defaults become `--option`
+flags. Keyword-only parameters (after `*`) always become options, and without a default they become
+required options.
+
+Underscores in parameter names are converted to dashes in the generated flag, so `dry_run` becomes
+`--dry-run`. The Python identifier you read inside the function body keeps its underscored form
+(`args.dry_run`). To opt out, pass explicit names via `Option("--my_flag", ...)`.
+
+```py
+from cmd2 import with_annotated
+
+class MyApp(cmd2.Cmd):
+    @with_annotated
+    def do_greet(self, name: str, count: int = 1, loud: bool = False):
+        """Greet someone."""
+        for _ in range(count):
+            msg = f"Hello {name}"
+            self.poutput(msg.upper() if loud else msg)
+```
+
+The command `greet Alice --count 3 --loud` parses `name="Alice"`, `count=3`, `loud=True` and passes
+them as keyword arguments.
+
+## How annotations map to argparse
+
+The decorator converts Python type annotations into `add_argument()` calls:
+
+| Type annotation                                          | Generated argparse setting                          |
+| -------------------------------------------------------- | --------------------------------------------------- |
+| `str`                                                    | default (no `type=` needed)                         |
+| `int`, `float`                                           | `type=int` or `type=float`                          |
+| `bool` with a default                                    | boolean optional flag via `BooleanOptionalAction`   |
+| positional `bool`                                        | parsed from `true/false`, `yes/no`, `on/off`, `1/0` |
+| `Path`                                                   | `type=Path`                                         |
+| `Enum` subclass                                          | `type=converter`, `choices` from member values      |
+| `decimal.Decimal`                                        | `type=decimal.Decimal`                              |
+| `Literal[...]`                                           | `type=literal-converter`, `choices` from values     |
+| `Collection[T]` / `list[T]` / `set[T]` / `tuple[T, ...]` | `nargs='+'` (or `'*'` if it has a default)          |
+| `tuple[T, T]`                                            | fixed `nargs=N` with `type=T`                       |
+| `T \| None`                                              | unwrapped to `T`, treated as optional               |
+
+When collection types are used with `@with_annotated`, parsed values are passed to the command
+function as:
+
+- `list[T]` and `Collection[T]` as `list`
+- `set[T]` as `set`
+- `tuple[T, ...]` as `tuple`
+
+Unsupported patterns raise `TypeError`, including:
+
+- unions with multiple non-`None` members such as `str | int`
+- mixed-type tuples such as `tuple[int, str]`
+- `Annotated[T, meta] | None`; write `Annotated[T | None, meta]` instead
+
+The parameter names `dest` and `subcommand` are reserved and may not be used as annotated parameter
+names.
+
+## Annotated metadata
+
+For finer control, use `typing.Annotated` with [Argument][cmd2.annotated.Argument] or
+[Option][cmd2.annotated.Option] metadata:
+
+```py
+from typing import Annotated
+from cmd2 import Argument, Option, with_annotated
+
+class MyApp(cmd2.Cmd):
+    def sport_choices(self) -> cmd2.Choices:
+        return cmd2.Choices.from_values(["football", "basketball"])
+
+    @with_annotated
+    def do_play(
+        self,
+        sport: Annotated[str, Argument(
+            choices_provider=sport_choices,
+            help_text="Sport to play",
+        )],
+        venue: Annotated[str, Option(
+            "--venue", "-v",
+            help_text="Where to play",
+            completer=cmd2.Cmd.path_complete,
+        )] = "home",
+    ):
+        self.poutput(f"Playing {sport} at {venue}")
+```
+
+Both `Argument` and `Option` accept the same cmd2-specific fields as `add_argument()`: `choices`,
+`choices_provider`, `completer`, `table_columns`, `suppress_tab_hint`, `metavar`, `nargs`, and
+`help_text`.
+
+`Option` additionally accepts `action`, `required`, and positional `*names` for custom flag strings
+(e.g. `Option("--color", "-c")`).
+
+When an `Option(action=...)` uses an argparse action that does not accept `type=` (`count`,
+`store_true`, `store_false`, `store_const`, `help`, `version`), `@with_annotated` removes any
+inferred `type` converter before calling `add_argument()`. This matches argparse behavior and avoids
+parser-construction errors such as combining `action='count'` with `type=int`.
+
+When a user-supplied `choices_provider` or `completer` overrides an inferred `Enum` or `Literal`,
+the restrictive type converter is also dropped so the user-supplied values are not rejected at parse
+time. The `Path` converter is permissive and is preserved when a custom completer is provided.
+
+## Decorator options
+
+`@with_annotated` currently supports:
+
+- `ns_provider` -- prepopulate the namespace before parsing, mirroring `@with_argparser`
+- `preserve_quotes` -- if `True`, quotes in arguments are preserved
+- `with_unknown_args` -- if `True`, unrecognised arguments are passed as `_unknown`
+- `subcommand_to` -- register the function as an annotated subcommand under a parent command
+- `base_command` -- create a base command whose parser also adds subparsers and exposes
+  `cmd2_handler`. A `cmd2_handler` parameter is only valid on a command decorated with
+  `base_command=True`; declaring one elsewhere raises `TypeError`.
+- `help` -- help text for an annotated subcommand
+- `aliases` -- aliases for an annotated subcommand
+
+```py
+@with_annotated(with_unknown_args=True)
+def do_rawish(self, name: str, _unknown: list[str] | None = None):
+    self.poutput((name, _unknown))
+```
+
+## Annotated subcommands
+
+`@with_annotated` can also build typed subcommand trees without manually constructing subparsers.
+
+```py
+@with_annotated(base_command=True)
+def do_manage(self, *, cmd2_handler):
+    handler = cmd2_handler
+    if handler:
+        handler()
+
+@with_annotated(subcommand_to="manage", help="list projects")
+def manage_list(self):
+    self.poutput("listing")
+```
+
+For nested subcommands, `subcommand_to` can be space-delimited, for example
+`subcommand_to="manage project"`. The intermediate level must also be declared as a subcommand that
+creates its own subparsers:
+
+```py
+@with_annotated(subcommand_to="manage", base_command=True, help="manage projects")
+def manage_project(self, *, cmd2_handler):
+    handler = cmd2_handler
+    if handler:
+        handler()
+
+@with_annotated(subcommand_to="manage project", help="add a project")
+def manage_project_add(self, name: str):
+    self.poutput(f"added {name}")
+```
+
+## Lower-level parser building
+
+If you need parser grouping or mutually-exclusive groups while still using annotation-driven parser
+generation, [cmd2.annotated.build_parser_from_function][cmd2.annotated.build_parser_from_function]
+also supports:
+
+- `groups=((...), (...))`
+- `mutually_exclusive_groups=((...), (...))`
+
+```py
+@with_annotated(preserve_quotes=True)
+def do_raw(self, text: str):
+    self.poutput(f"raw: {text}")
+```
+
+## Automatic completion from types
+
+With `@with_annotated`, arguments annotated as `Path` or `Enum` get automatic completion without
+needing an explicit `choices_provider` or `completer`.
+
+Specifically:
+
+- `Path` (or any `Path` subclass) triggers filesystem path completion
+- `MyEnum` (any `enum.Enum` subclass) triggers completion from enum member values
+
+With `@with_argparser`, provide `choices`, `choices_provider`, or `completer` explicitly when you
+want completion behavior.
+
+## Stability and feedback
+
+Because this feature is experimental:
+
+- Behavior of edge cases (mixed-type tuples, deeply-nested `Annotated`, conflicting metadata) may
+  change.
+- Diagnostic error messages may be reworded.
+- The set of supported type annotations may be expanded or trimmed.
+
+If you depend on `@with_annotated`, please share feedback and edge cases via the
+[issue tracker](https://github.com/python-cmd2/cmd2/issues) so behavior can be locked in before the
+feature graduates out of experimental.