Update documentation for arg attribute

[MiniaczQ]

Please complete the following tasks

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

Clap Version

4.4.0

Describe your use case

I've been porting a CLI application from clap ~2, to 4.4.0 with the goal being struct based arguments through derives.
One of the tests showed the change in behavior of --flag val1 val2, currently known as num_args.
It was impossible to find an example usage of this for derive-style in examples and docs.

I finally managed to find it through a lucky comment in this discussion, but knowing this and browsing the repository again, it revealed that this parameter is only mentioned a few times.

Describe the solution you'd like

Ideally there'd be docs and examples for every parameter arg (possibly other) macro accepts, so at least creating issues to add those examples would help a bit.

Alternatives, if applicable

No response

Additional Context

I'm not well versed in clap, this has been my first usage of it in a project.

[epage]

At this time we intentionally document how to use builder methods within the derive and only explicitly document attributes that have special meaning outside of the derive API.

#4090 is where we are discussing how this could be better communicated or improved. Closing in favor of that.