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

[martinjm97]

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

[2bndy5]

This suggestion about the doc string is very similar to the proposal in #93 which was rejected in favor of #98 (using a dataclass instead). IMO, the complexity of this suggestion may introduce sustainability problems in the long run.

I was hoping to use Annotated to provide other metadata about the argument, like what version of my CLI introduced support for that argument. That way I can generate a better CLI doc from the Tap derivative's members' type metadata.