search

TeXitoi / structopt

Parse command line arguments by defining a struct.
Other
2.7k stars 149 forks source link

Why the proc macro attribute `setting` is not documented in the big docs.rs page? #513

Closed alt-art closed 2 years ago

alt-art commented 2 years ago

I have searched at all docs.rs page for a way to make the ColoredHelp works in the structopt, but I just found the answer for this in an issue on GitHub.

TeXitoi commented 2 years ago

From https://docs.rs/structopt/latest/structopt/#raw-methods

They are the reason why structopt is so flexible. Every and each method from clap::App/Arg can be used this way!

alt-art commented 2 years ago

I don't see any mentions of the setting attribute.

alt-art commented 2 years ago

I think there should be at least basic documentation for this because I was super confused by it.

epage commented 2 years ago

The scope of raw methods is the entire clap builder API. That'd be quite overwhelming to read or maintain to have all of it in the structopt attribute documentation. There are examples of a couple of raw-method attributes to help the reader extrapolate how to use the rest.

How should we pick or choose what to prioritize in the examples vs leave for extrapolation? In this case, the confusion was over settings. For another, it could be something else.

I guess the next question is "how can we do a better job bridging users from structopt's documentation to clap's?". Until clap3, where they are merged, I don't have any good ideas for this.

TeXitoi commented 2 years ago

As @epage cleanly explained.

The setting attribute is documented here: https://docs.rs/clap/latest/clap/struct.App.html#method.setting

If you have any idea to how explain clearly that all of clap feature can be used, without redocumenting everything in structopt, I'd be open to any suggestion. There is always this kind of problem, and we try to fix is as we can within reasonable work. See for example https://github.com/TeXitoi/structopt/pull/511