Add support for using the `Annotated` type to provide comments for the help string

Tap currently gets the help strings from the comments:

from tap import Tap

class Args(Tap):
    count: int  # The number of chickens in the universe

However, https://docs.python.org/3/library/typing.html#typing.Annotated allows users to provide both a type and a comment. Using Annotated, the above code becomes:

from tap import Tap
from typing import Annotated

class Args(Tap):
    count: Annotated[int, "The number of chickens in the universe"]  # This won't show up in the help string
    """This too will not show up!"""

One edge case is whether or not we should ignore surrounding comments when an argument is annotated. We're thinking that whenever there's an annotation for an argument, we should ignore the surrounding comments. For example,

class Args(Tap):
    count: Annotated[int, "The number of chickens in the universe"]  # This won't show up in the help string
    """This too will not show up!"""

A potential issue with this design is that Annotated can be used to specify refinement types (e.g., that an argument is positive arg: Annotated[int, Gt(0)]). A solution would be to have a custom Tap class for HelpString and then only use annotations when the annotation is of type HelpString. For example,

class Args(Tap):
    count: Annotated[int, HelpString("The number of chickens in the universe")]

would provide the help string, but

class Args(Tap):
    count: Annotated[int, "The number of chickens in the universe"]

and

from annotated_types import Gt

class Args(Tap):
    count: Annotated[int, Gt(0)]

would not contribute to the command line help string.

Another thought is that we could potentially support verification as in pydantic.

--JK

swansonk14 / typed-argument-parser

Add support for using the `Annotated` type to provide comments for the help string #127