"Undocumented" derive attributes

[epage]

Probably the most frequent support issue with the derive API is so called "raw attributes" which forward directly to the builder API.

For example:

• docs: Add #[clap(global)] example & docs #4087
• Undocumented Derive Attributes #3925
• Derive reference doesn't mention group #3754
• Derive documentation can be improved #3189
• Derive: how to enable trailing_var_arg with derive #4334
• How to use ArgAction::Append with derive instead of builder? #4331
• Clap derive is missing "hide" option #4353
• https://www.reddit.com/r/rust/comments/12jhmxz/clap_zero_or_more_arguments_possible_with_derive/jg3b5xh/
• propagate_version is missing from documentation #5345

Our stance has been that we have intentionally decided to not enumerate every possible attribute in the derive documentation due to the maintenance burden of that. Instead the derive reference explains how raw attributes work and reminds people when looking at Command attributes that raw attributes exist, linking to the relevant documentation for using those raw attributes.

How can we improve discoverability, reduce confusion, and ideally keep maintenance costs down?

[jaskij]

Tutorial

First of all, doing a text search for "raw" on the rendered tutorial doesn't yield any results. Looking through it quickly, maybe the tutorial could use a section on how clap uses attributes? They're mentioned in a few places they get a short mention, but nothing dedicated to them.

Reference

Also, people have a tendency to skip around, especially if a document is titled "Reference". Many readers will probably skip a section called "Terminology", and only go back to it if they don't understand a term. As it currently only describes magic vs raw attributes, I'd change the title (maybe something like "Attribute types"?), and possibly add a "Terminology" section in the future if it is necessary.

[jaskij]

Thinking further, I believe that raw attributes in places like the Command Attributes section simply do not draw enough attention.

Doing a quick test, I found that after going to the heather (either via ToC or a hardlink), the eye just has a tendency to skip over and is drawn to the name attribute - simply because that's what someone would be expecting. I'm not sure what tools, if any, exist in Markdown to make "Raw attributes" stand out enough. Ideally, I'd be thinking of something similar to AsciiDoctor's admonitions

[MultisampledNight]

For me too, the page was so long that I simply skipped the lengthy top part to get to the examples. I think a well commented full example might serve a better job than this lengthy tutorial, should someone just want to pick up and implement their CLI.

[MultisampledNight]

(and to be fair, it did take quite a while until I found out that some options can have omitted values which will be autogenerated, while others must be explicitly specified all the time. At first I thought long and short were bools and specifying them was setting them to true — like a CLI.)

[epage]

For me too, the page was so long that I simply skipped the lengthy top part to get to the examples.

From context I'm assuming this is referring to the tutorial.

I think a well commented full example might serve a better job than this lengthy tutorial, should someone just want to pick up and implement their CLI.

For this, we offer the cookbook which includes things like a git CLI so people can see how to reproduce a feature from git.

[MultisampledNight]

Ah oh, I completely missed that. Thank you!

[Firstyear]

So what happened to me was my goal was 'to hide an attribute'. So first step was to look at https://docs.rs/clap/latest/clap/_derive/index.html and to cmd-f for "hid" to match hide or hidden. When nothing matched, I looked manually at https://docs.rs/clap/latest/clap/_derive/index.html#command-attributes and didn't see anything there.

At that point I wondered "is hiding even supported?" so I searched it in the api docs https://docs.rs/clap/latest/clap/?search=hid here, which led me to https://docs.rs/clap/latest/clap/builder/struct.Command.html#method.hide

So at this point I knew hiding was possible, but I couldn't connect how to connect that with derive.

It turned out the answer was "https://docs.rs/clap/latest/clap/_derive/index.html#terminology" but I didn't see that because it was above the Command attribute section! There is a similar comment in Command attributes but because I saw that before I searched for the method and I was focused on the goal, I didn't connect that I could use the method as an attribute here.

So I'm not 100% sure on how to "improve" this. I think generally as a developer when we are looking for something we already know, we don't read top to bottom, but try to narrow down to a specific point for that implementation detail, which in this case meant that I missed the information that connected these concepts.

Even maybe something as silly as a list of the methods that can be used as attributes in the raw attributes section would help because then people can see the connection? It doesn't need full examples or explanations, but it would help people to "see" that it's possible.

Alternately, the reverse, where "https://docs.rs/clap/latest/clap/builder/struct.Command.html#method.hide" shows an example of it use as an attribute?

[epage]

Thank you! Having a report where you step through your thought process is very helpful!

Even maybe something as silly as a list of the methods that can be used as attributes in the raw attributes section would help because then people can see the connection? It doesn't need full examples or explanations, but it would help people to "see" that it's possible.

A raw list without any other details reduces maintenance but still has some maintenance burden to it. If we made them intra-doc links, that will catch removes. We couldn't easily be able to catch API additions though.

Alternately, the reverse, where "https://docs.rs/clap/latest/clap/builder/struct.Command.html#method.hide" shows an example of it use as an attribute?

I hesitate from past experience in dealing with documentation that overlayed two different APIs. When YAML was support, it was documented along with the builders and the disruption to the flow of the documentation bothered me. The longer the documentation, the more likely people will miss things. Throw in irrelevant content and it becomes even worse.

[Firstyear]

Yeah, there really isn't a "perfect" solution here. I think the doc links could work well enough though in this case :)

[lgarron]

I came here for the same concern — spent quite some time trying to figure out how to hide a legacy argument using the derived pattern. It doesn't help that searches like https://docs.rs/clap/latest/clap/index.html?search=verbatim_doc_comment return no result, so I don't know if there's a similar keyword that I'm also missing.

Even maybe something as silly as a list of the methods that can be used as attributes in the raw attributes section would help because then people can see the connection? It doesn't need full examples or explanations, but it would help people to "see" that it's possible.

I would really love to see something like this.

The docs are already a bit long, so I think it wouldn't hurt to make them very useful by erring on the side of more discoverable examples.

[epage]

The docs are already a bit long, so I think it wouldn't hurt to make them very useful by erring on the side of more discoverable examples.

Might be good to start a new thread, discussion, or issue on this so we can better dig into problems you ran into with example discoverability.

[rben01]

I was going to leave an issue about the lack of documentation of Derive API attributes. Thankfully the issue template directed me here!

Anyway, I agree that derive attributes are very hard to find. I looked in the tutorial and found a bunch of disparate examples of how to use attributes, but these only covered the common cases and didn't really provide a jumping-off point to help me go beyond, or learn how to go beyond, what was covered there. (In this regard it's a bit more more like a cookbook than a tutorial.) (I just now realized that the tutorial does say “You can use attributes to change the application level behavior of clap. Any Command builder function can be used as an attribute.”, but it's pretty discreet, sandwiched between two code blocks.)

Then, in the reference, I stumbled upon the magic sentence:

Raw attributes are forwarded directly to the underlying clap builder. Any Command, Arg, or PossibleValue method can be used as an attribute.

This was when the lightbulb went off: if you don't know how to do something with the derive API, but you know it doesn't involve a magic attribute, then the way to find out how to accomplish your goal is to search for a reasonably-named method in the builder API and just use that method as an attribute.

I think that this concept should be plastered everywhere in clap’s derive API documentation and you should never have to scroll too far to see it.

One way to achieve this, which I think would also be helpful more generally, would be to have a “Concepts” section in the tutorial, probably above the “Quick Start” section, which lays out the basic concepts of the derive API:

1. Your parser is a struct, and “parsing” means reading the provided command line arguments into the struct's fields
2. You can #[derive] Parser, Subcommand, and ValueEnum, which reduce the amount of code you need to write to implement common CLI parser workflows (need feature derive, of course)
3. You can control how deriving works by annotating fields with attributes like #[arg(short, long, default_value_t=...)]
4. There is a list of “magic” attributes (provide a few examples of the most commonly used ones) that clap understands
5. Clap also understands all of the methods available on Command, so if you want to customize behavior further then just use those methods as attributes (and provide a few examples)
6. To get the values out of a parser, call Cli::parse()

If there's consensus on this I'd be happy to submit a small docs PR.

[1oglop1]

100% agree with this. I am very new to Rust (my main background is Python), trying to create a CLI app or read the existing code in our codebase. Unfortunately rust-analyzer in VS Code is absolutely useless here and does not take me to any relevant documentation nor it displays anything when hovering over macros like #[arg(long, env, default_value_t = Ipv4Addr::new(0, 0, 0, 0))].
I spent over 30 minutes trying to find where default_value_t is documented and did not find absolutely anything.

When learning new libraries I try to rely on these things in order:

1. Quick start
2. IDE integration
3. intuitive API
4. Search in Docs
5. Reading all docs sections on my own

I have dyslexia and reading a lot of text is often a problem for me. Simply put. I can write the code only thanks to the syntax highlighter. So when I open a new web page I am looking at the largest pieces, eg. headlines or code examples. As a consequence, I unintentionally forget/ignore other pieces of text, therefore good documentation structure is very important for me.

I worked with other rust packages (do not remember which one) that had a link to the concepts page which was for me extremely helpful.

It is important to write docs for someone who has never seen/used the project. Writing the docs myself I use two rules: "Explain this so that my even grandma can use it" (she could barely use the phone, let alone the computer) or "Explain this to the 5 year old kid" - using simple concepts and examples.
The current state of the docs is for someone familiar with the concepts. And it would greatly benefit from the two concepts I mentioned above.

[epage]

@1oglop1

I spent over 30 minutes trying to find where default_value_t is documented and did not find absolutely anything.

@lgarron

It doesn't help that searches like https://docs.rs/clap/latest/clap/index.html?search=verbatim_doc_comment return no result, so I don't know if there's a similar keyword that I'm also missing.

This is a problem with the search itself as it doesn't know about derive attributes.

What we can do for that is we can take all the "magic-only" attributes and mark them as aliases for the derive reference. That way when you search for default_value_t, it'll point you to the reference.

[epage]

See #4984

[tgrushka]

It is important to write docs for someone who has never seen/used the project. Writing the docs myself I use two rules: "Explain this so that my even grandma can use it" (she could barely use the phone, let alone the computer) or "Explain this to the 5 year old kid" - using simple concepts and examples.
The current state of the docs is for someone familiar with the concepts. And it would greatly benefit from the two concepts I mentioned above.

Really. You can say that again and again! The docs in many crates are written by the author, for the author, who often assumes everyone else thinks like they do and therefore should just know how it works. That's almost never the case. Everyone's brain operates differently. We all think differently, and that's a good thing. We need to be good communicators, not just good coders. If someone cannot document their code enough for at least an 8th grader to understand, they probably shouldn't be publishing crrates. If no one is able to figure out your tool, and you don't document it, it is not that "they don't deserve the benefit" -- it's probably more like "you don't deserve the recognition."

[epage]

@tgrushka please be careful with your tone as your post comes across as gate keeping and borderlines on being hostile / derogatory towards others efforts, particularly without any nuance for why things end up the way they end up.

[epage]

While its not a definitive fix, I'm hoping that #4985 is an incremental improvement

[epage]

Kind of an out-there idea is we could create a cargo xtask to use rustdoc json output (nightly only) to extract all of the builder methods that may be used as an attribute and inject that into the reference, linking to the builder methods. This would improve discoverability but wouldn't help with providing derive-specific examples. We'd also have to deal with the overlap between magic attributes that also have a builder method.

[epage]

cargo-semver-checks is using https://docs.rs/rustdoc-types/latest/rustdoc_types/index.html for parsing the rustdoc json.

[epage]

Right now, I'm leaning towards a bullet list of all raw attributes for a type in a format similar to magic attributes (<name> = <something> when single argument, <name>(<something>) for multi-argument). <name> would link to the builder method and <something> can use the arg name but link to the arg type.

The list will be big, Keeping our flat derive ref will likely be a no-go. Having a page for raw attributes will be bad for searching. We likely will need a page per attribute type with magic and then raw attributes. We can use #[doc(path)] to pull in the generated pages.

[scouten]

Frankly, I don't think this approach is a good idea. I came here via #1751 and feeling very frustrated by the responses in that thread.

I eventually found the answer to the question I was asking via Stack Overflow or similar. To me that suggests there is a usability issue here and to read that you are intentionally not providing the missing documentation is … not encouraging.

I hope that you will find it in your hearts to reconsider this approach.

[tgrushka]

Maintaining good documentation is not hard if:

1. you authored the library
2. you use AI to help you generate it, and then you validate it, because you know if it's correct or not
3. you include examples
4. you document things at the function level, and then maintain an overview / README of how to do basic things, and point to the relevant functions
5. docs.rs even organizes the docs for you.

If you have 2 days to spend coding a new feature or a breaking change, you have one extra hour to document it. Lack of time is not an excuse.

So there really is no excuse today, with all the AI tools available to us to help us write decent English. AI docs may not be the most succinct or understandable, but they are better than nothing, and certainly the library author would be able to judge their correctness as to how they intended their library to work and be used.

[epage]

See also my post at #4090 (reply in thread)