Overengineered

[fade2black]

I think this crate (as well as many many others) needs to be documented rather than constantly adding features and macros.
That said, I observe the same trend like in Ruby community: in Ruby people tend to overcomplicate simple things by using metaprogramming and 10-level of inheritance. In Rust people tend to add features and macros (metaprogamming). In both cases documentation is very poor. And when you raise this issue you get answer: "it is open source f..k off and don't use if you don't want to use it". I'd prefer to use well documented traits rather than ugly macros.

[kbknapp]

I'd like to address a few points you raised.

First, and foremost:

And when you raise this issue you get answer: "it is open source f..k off and don't use if you don't want to use it".

If you've received this kind of answer please raise it to the attention of myself, @epage or one of the clap admins. That language is absolutely not an acceptable answer. You don't have to use anything you don't want, but anyone using language like that should think twice about their involvement in this project (and probably open-source in general).

---

If you feel the documentation is poor, please open issues on the items you wish to be better documented. I won't disagree that documentation could be better in areas, but clap has a lot of documentation. People are also usually very quick to answer specific questions when the documentation is incomplete or ambiguous. However, discussions like these aren't actionable. "The documentation is very poor, please redo."

---

As far as macros go, clap primarily uses the derive macros which should be both well documented (if not again please file issues with specifics), and standard in Rust.

There are the older macro_rules macros, but those are both not widely used, nor required to use in nearly any capacity.

---

Finally, striking a particular nerve of mine; argument parsing in the general sense is not simple. It seems simple yes, but it turns out it is quite complex when handling edge-cases and features that many consider standard. A problem with argument parsing in general is that everyone has ideas of which parts are "standard use" and everyone's ideas don't have a lot of overlap.

There are quite a few argument parsing libraries in Rust. Many of which make trade-offs for things like binary size or simplicity at the expense of features/error messages/niceties. These are valid trade-offs, and if you'd prefer something other than clap that is perfectly fine! I'd suggest taking a look at any of:

• argh
• bpaf
• gumpdrop
• lexopt
• pico-args
• xflags
• getopts

[epage]

See also https://github.com/rosetta-rs/argparse-rosetta-rs for a very high level comparison of packages

[epage]

I think this crate (as well as many many others) needs to be documented rather than constantly adding features and macros.
.... In Rust people tend to add features and macros (metaprogamming). In both cases documentation is very poor.

The state of our documentation

• Everything within the API is documented and what most people will interact with of the builder API have examples.
• A couple of years ago, we added tutorials and cookbooks. A couple of cookbook items lack derive implementations and we should have an open issue for this.
• There are still some frustration points within the documentation. "Undocumented" derive attributes #4090 is an example.

Normally, when there is push back on requests for documentation, it is usually a combination of

• How do we fit this in to the narrative of the documentation?
  • A lot of requests boil down to "I ran into this problem so therefore its general and should be in the tutorial" when, relative to the existing tutorial, its more specialized and we'd need to extend the narrative a lot to fit some of those more niche cases in
• What is the maintenance load of this documentation? This is the big challenge with "Undocumented" derive attributes #4090
  • This isn't "a couple of paragraphs or one or two examples" is hard to maintain but "duplicating all of our builder documentation for the derive" or adding 60 new examples is harder to maintain
  • Documentation tooling improvements would help. Someone was leading the charge on this but moved on and no one else stepped in

As for endlessly adding features, we've been doing the opposite. Over the last several years, we've also done work to remove features, trying to find ways to take two or three features and merge them together or removing lesser used parts of the API that users have other ways of resolving. I also push back on a lot of feature requests because of their impact on API complexity, binary size, and build time when their use case is too specialized.

We have also removed some of the macro_rules APIs and have an open issue to remove more.

I'd prefer to use well documented traits rather than ugly macros.

As for our derive / proc-macro API, it is a wrapper around our builder API. The builder API is both more powerful and more extensively documented (see #4090 again).