Port StructOpt's exhaustive derive documentation

[epage]

Issue by epage
Tuesday Oct 12, 2021 at 14:29 GMT
Originally opened as clap-rs/clap#2856

---

Please complete the following tasks

• I have searched the discussions
• I have searched the existing issues

Clap Version

v3.0.0-beta.4

Where?

Unsure

What's wrong?

This is being split out of #1661. We do not talk about magic methods, etc.

Related is #1671

How to fix?

Rewrite structopt's docs for clap_derive

Where is a question. I'm assuming the bulk would go on Parser with the other related traits and README pointing to that.

[epage]

Comment by pksunkara
Tuesday Oct 12, 2021 at 14:44 GMT

---

Most of the guide would be in the README of clap_derive which should be #[doc(include_str)] into the src/lib.rs.

[epage]

Comment by epage
Tuesday Oct 12, 2021 at 14:49 GMT

---

I'm concerned about people discovering the docs there since most people will get clap_derive through clap and won't think about the underlying proc macro crate (I've never look at structopt-derive, serde-derive, etc).

[epage]

Comment by pksunkara
Tuesday Oct 12, 2021 at 15:13 GMT

---

That would be okay to as long as we point clap_derive (readme & lib) to those traits.

Or the reverse, point the traits to derive macro documentation since we also point to clap_derive in clap readme and lib docs. I don't think there is an issue of discoverability.

I don't mind either way in any case.

[epage]

Comment by gibfahn
Friday Nov 26, 2021 at 12:11 GMT

---

This was the biggest issue when moving from StructOpt -> clap 3 beta -> newer clap 3 beta for me. It's really hard to know what the actual options are you can pass to the Parser, and what format they should be in.

Filed a PR for this at clap-rs/clap#3052 , I think this is what the discussion here points to, let me know whether this approach makes sense.