search

epage / clapng

A full featured, fast Command Line Argument Parser for Rust
docs.rs/clap
Apache License 2.0
0 stars 0 forks source link

Port StructOpt's exhaustive derive documentation #214

Open epage opened 2 years ago

epage commented 2 years ago

Issue by epage Tuesday Oct 12, 2021 at 14:29 GMT Originally opened as https://github.com/clap-rs/clap/issues/2856

Please complete the following tasks

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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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 https://github.com/clap-rs/clap/pull/3052 , I think this is what the discussion here points to, let me know whether this approach makes sense.