[suggestion] Use a custom type for help string instead of source code parsing.

[Cnoor0171]

An alternate suggestion to #93

Instead of parsing source code (which many will find surprising behavior), a cleaner and more intuitive approach would be to use a custom type that's capable of taking the extra meta information. This pattern is well established by both the standard library and other popular third party libraries like dataclass, sqlalchemy, pydantic etc. For example, when you declare a dataclass,

from dataclass import dataclass, field
@dataclass
class User:
    name: str = "John Doe"  # This is the normal way of setting the default
    password: str = field("p@ssw0rd", repr=False)  # This allows setting the default AND other properties

In case of tap, the declaration would look something like

from tap import Tap, Arg
class SimpleArgumentParser(Tap):
    language: str = 'Python'
    package: str = Arg('Tap', help="Package name")  # Now I can leave comments that don't affect behavior!! e.g.: pylint: disable=...

[swansonk14]

Hi @Cnoor0171,

Thank you for the suggestion! We agree that source code parsing is not ideal, but we still think that comment-based help strings provide the cleanest user experience and allow a single source of documentation both in code and on the command line. Therefore, we plan to keep it as the default.

However, since you and others are interested in an option that does not require source code parsing, we would love to support an alternative as well. We like your suggestion of an Arg with a help string and we would welcome a PR implementing your solution.

Thanks,
Jesse and Kyle

[purepani]

provide the cleanest user experience

This comment/help string feature was a rather terrifying feature to me. I would expect that changing something in a comment or a doc string doesn't change the behavior of the program, which this does. While the feature is certainly useful for the stated reasons, given how fragile and surprising it is, and given how the Annotated and default function pattern are extremely well established, I personally think it should be an opt in feature instead of opt out.

[martinjm97]

I would expect that changing something in a comment or a doc string doesn't change the behavior of the program, which this does.

I would too, but I don't really think that this is a fair characterization. In the same way that standard tools turn comments into documentation (e.g., pydoc), Tap turns comments into documentation in the CLI.

given how the Annotated and default function pattern are extremely well established

My understanding is that Annotated was introduced in Python 3.9. Perhaps once 3.8 is phased out, we can consider changing the default to Annotated, but it's still less slick.

[purepani]

The reason this is different for me than pydoc is because pydoc generates documentation independent of the rest of the program, whereas this library is combining both the functionality of docgen and implementation into one.

Also, I would consider CLI documentation to be part of the program behavior, since it's not different than, say, writing to standard output with a command.
Additionally, using comments/docstrings for this just makes it more cumbersome to do more dynamic things with the help docs as opposed to, say, the default field pattern or the annotated pattern.

You're certainly free to disagree with my view here; I just wanted to say it because at least I feel quite strongly that this is a pretty serious antipattern, to the point where I'd rather roll a custom version of this library(especially since this way of working is default), rather than just use the library, and I'm sure I'm not the only person who feels that strongly(though I wouldn't be surprised if I'm in a minority)

Personally, I think a good solution would be to use the default field pattern(I don't know what it's actually called, so I hope this makes sense) or annotated pattern should be the preferred method, and a decorator should be used on the class to explicitly opt in to this feature if it's desired.

[sliedes]

Is it possible to disable the comment parsing completely? I use a strict linter that produces a warning unless I add a "# type: ignore" on what it sees as an uninitialized variable declared in the class; and even if the field has a docstring, that "# type: ignore" gets appended to it...