Why the proc macro attribute `setting` is not documented in the big docs.rs page?
Closed this issue · 5 comments
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.
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!
I don't see any mentions of the setting attribute.
I think there should be at least basic documentation for this because I was super confused by it.
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.
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 #511