Skip to content

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

New issue

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

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

Already on GitHub? # to your account

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
# for free to join this conversation on GitHub. Already have an account? # 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