Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Remove rustdoc automatic link markup in clap_derive-generated help messages #3019

Closed
2 tasks done
AntonHermann opened this issue Nov 12, 2021 · 2 comments
Closed
2 tasks done
Labels
A-derive Area: #[derive]` macro API

Comments

@AntonHermann
Copy link

AntonHermann commented Nov 12, 2021

Please complete the following tasks

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

Clap Version

3.0.0-beta.5

Describe your use case

When using URLs in doc comments like "see https://repo.com for details", rustdoc emits a warning suggesting the automatic link syntax: "see <https://repo.com\> for details".

When clap uses this doc comment to generate help messages, it outputs the automatic link markup (angle brackets) as it was written instead of removing the markup, leaving only the url in place.

Describe the solution you'd like

Removing the automatic link markup and just using the URL in the help message would be a good solution in my opinion.

One could also consider emitting the ansi control sequence to markup links in the terminal on linux (see this writeup for details, terminal support, etc.) so they are clickable in many terminal emulators.

Alternatives, if applicable

Leaving everything as is, meaning that users who want to use rustdocs automatic links but don't want them to show up in help output would have to duplicate their help message and pass it to #[clap(about = "...")] or #[clap(long_about = "...")].
(I haven't checked whether those take preference over doc-comments, if they do not then it would be impossible to have working links in rustdoc while not having the link markup in the clap output?)

Additional Context

No response

@epage epage added the A-derive Area: #[derive]` macro API label Nov 12, 2021
@epage
Copy link
Member

epage commented Nov 12, 2021

Thanks for the feedback!

I suspect there are other improvements to be made in our post-porcessing. The challenge will be in finding the right balance between implementation cost and quality.

@pksunkara
Copy link
Member

This can be closed since #2389 covers it already.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-derive Area: #[derive]` macro API
Projects
None yet
Development

No branches or pull requests

3 participants