Explicitly doc the usage of ArgEnum

[Banyc]

Please complete the following tasks

• I have searched the discussions
• I have searched the open and rejected issues

Clap Version

3.1.9

Describe your use case

Searching google for "rust clap enum example" yields no results or outdated macro arg_enum.

The expected answer should be:

#[derive(clap::Parser)]
struct Args {
    #[clap(arg_enum)]
    level: Level,
}

#[derive(clap::ArgEnum, Clone)]
enum Level {
    Debug,
    Info,
    Warning,
    Error,
}

Describe the solution you'd like

Explicitly show the example and usage in README.md.

Alternatives, if applicable

No response

Additional Context

No response

[epage]

You have several routes to the documentation

• On the arg_enum page, click "Go to latest release" and show a search result for the ArgEnum trait which gives a derive example
• On the docs click on "Tutorial: .... Derive API" and scroll down to the validation section for enumerated values
• On the docs click on "Derive Reference" and you will see how to use it and what attributes are supported.

[Banyc]

@epage I totally ok with the suggestions as a user who have just found the correct usage. But as for new learners stumbling across this, they might still find it a hard time looking for answers. In their (including mine) points of views, the doc is not clear and easy enough, especially comparing to that of C#. I am really impressed by Rust language and its safety features. That's why I want the ecosystem around the language could be more friendly to new learners. I hope the usage is only one search away, not nested in links within links imho.

[epage]

Isn't that similar to our tutorial, with the main difference being that our code isn't inline?

The lack of inline code is not great but its a side effect of making our code samples testable. If we switched to a mdbook, we could have them inline. #3189 is exploring the needs for our derive documentation.

What I'm trying to understand is a concrete user need that we can explore improving or a concrete solution we can evaluate applying.

[Banyc]

@epage

a concrete solution

I fully agree with this!

[epage]

Without anything actionable and the fact that the reported problem (documenting ArgEnum) is done, I'm going to go ahead and close this. If you have specific concerns or specific solutions, feel free to open new issues.