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

rustdoc: Suggest to turn 'http...' into an automatic link #77501

Closed
HackAttack opened this issue Oct 3, 2020 · 6 comments · Fixed by #81764
Closed

rustdoc: Suggest to turn 'http...' into an automatic link #77501

HackAttack opened this issue Oct 3, 2020 · 6 comments · Fixed by #81764
Labels
A-diagnostics Area: Messages for errors, warnings, and lints A-markdown-parsing Area: Markdown parsing for doc-comments A-suggestion-diagnostics Area: Suggestions generated by the compiler applied by `cargo fix`. C-feature-request Category: A feature request, i.e: not implemented / a PR. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.

Comments

@HackAttack
Copy link
Contributor

It would be nice if a raw hyperlink (with no markup) in a doc comment were rendered out as an anchor tag, à la GitHub. Otherwise you have to write

/// Check out this link: [https://example.com](https://example.com)
fn foo();

This would maximize readability in the code while slightly improving the generated HTML.

@jonas-schievink jonas-schievink added C-feature-request Category: A feature request, i.e: not implemented / a PR. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. labels Oct 3, 2020
@jyn514
Copy link
Member

jyn514 commented Oct 3, 2020

You can write <https://example.com> instead. I don't think rustdoc should add more custom markdown extensions.

@jonas-schievink
Copy link
Contributor

You can also use <https://example.com>, which imo is the proper way to do raw URLs in markdown.

@HackAttack
Copy link
Contributor Author

Well how about that…this was not clear from any documentation I found. Thanks, this is certainly good enough, though I will note that GitHub, Bitbucket, and the IntelliJ Rust plugin all auto-link in this way, so it might still be worth considering from a least-surprise perspective.

@jyn514
Copy link
Member

jyn514 commented Oct 3, 2020

It's documented here: https://www.markdownguide.org/basic-syntax#urls-and-email-addresses

Maybe rustdoc should link to a markdown guide? I don't think it necessarily needs to document all of markdown though.

@estebank
Copy link
Contributor

estebank commented Oct 3, 2020

It would be reasonable to have a warm by default lint for this with a structured suggestion.

@jyn514 jyn514 added A-diagnostics Area: Messages for errors, warnings, and lints A-suggestion-diagnostics Area: Suggestions generated by the compiler applied by `cargo fix`. labels Oct 3, 2020
@jyn514 jyn514 changed the title rustdoc: Auto hyperlink raw URLs rustdoc: Suggest to turn 'http...' into an automatic link Oct 11, 2020
@GuillaumeGomez
Copy link
Member

Adding a lint for this then!

Dylan-DPC-zz pushed a commit to Dylan-DPC-zz/rust that referenced this issue Oct 16, 2020
GuillaumeGomez added a commit to GuillaumeGomez/rust that referenced this issue Oct 16, 2020
Dylan-DPC-zz pushed a commit to Dylan-DPC-zz/rust that referenced this issue Nov 6, 2020
…, r=jyn514,ollie27

Add non_autolinks lint

Part of rust-lang#77501.

r? `@jyn514`
bors added a commit to rust-lang-ci/rust that referenced this issue Nov 6, 2020
…r=jyn514,ollie27

Add non_autolinks lint

Part of rust-lang#77501.

r? `@jyn514`
@jyn514 jyn514 added the A-markdown-parsing Area: Markdown parsing for doc-comments label Nov 12, 2020
@bors bors closed this as completed in 9aed9c1 Apr 8, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-diagnostics Area: Messages for errors, warnings, and lints A-markdown-parsing Area: Markdown parsing for doc-comments A-suggestion-diagnostics Area: Suggestions generated by the compiler applied by `cargo fix`. C-feature-request Category: A feature request, i.e: not implemented / a PR. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.
Projects
None yet
Development

Successfully merging a pull request may close this issue.

5 participants