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 can't create link to trait implementation with generics ([link](#impl-Trait-for-Type<G1, G2>)) #105600

Open
StackOverflowExcept1on opened this issue Dec 12, 2022 · 5 comments
Labels
A-intra-doc-links Area: Intra-doc links, the ability to link to items in docs by name 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

@StackOverflowExcept1on
Copy link
Contributor

I tried this code: (bit modified, taken from https://github.com/StackOverflowExcept1on/simple-graph/blob/master/simple-graph/src/graph.rs)

/// ### Serialization to [`String`] in Trivial Graph Format
/// See [`impl<V, E> Display for Graph<V, E>`](#impl-Display-for-Graph<V, E>)
///
/// ### Deserialization from [`&str`] in Trivial Graph Format
/// See [`impl<V, E> FromStr for Graph<V, E>`](#impl-FromStr-for-Graph<V%2C%20E>)

I expected to see this happen: you can create link in rustdoc to #impl-Trait-for-Type<Generic1, Generic2, Generic3, ...>
image1

Instead, this happened: without manually URL-encoding rustdoc can't create link to trait implementation
image2

Fast way to reproduce issue with rustdoc

git clone https://github.com/StackOverflowExcept1on/rustdoc-issue.git
cd rustdoc-issue
cargo doc
firefox target/doc/rustdoc_issue/struct.Type.html

Meta

rustc --version --verbose:

rustc 1.68.0-nightly (bdb07a8ec 2022-12-11)
binary: rustc
commit-hash: bdb07a8ec8e77aa10fb84fae1d4ff71c21180bb4
commit-date: 2022-12-11
host: x86_64-unknown-linux-gnu
release: 1.68.0-nightly
LLVM version: 15.0.6
@StackOverflowExcept1on StackOverflowExcept1on added the C-bug Category: This is a bug. label Dec 12, 2022
@fmease
Copy link
Member

fmease commented Dec 12, 2022

@rustbot label T-rustdoc A-intra-doc-links

@rustbot rustbot added A-intra-doc-links Area: Intra-doc links, the ability to link to items in docs by name T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. labels Dec 12, 2022
@camelid
Copy link
Member

camelid commented Dec 16, 2022

Hmm, I don't think this is a bug. When you use [...](#...) syntax, you're not using intra-doc links; rather, you're creating a manual URL link that you want rustdoc to output as if you'd written an HTML <a href="#...">...</a> tag. It is a limitation of rustdoc that you can't link to individual impls, but I don't think this is a bug.

@camelid camelid added C-feature-request Category: A feature request, i.e: not implemented / a PR. and removed C-bug Category: This is a bug. labels Dec 16, 2022
@StackOverflowExcept1on
Copy link
Contributor Author

@camelid would be cool to automatically encode URL then. Right now developer need to encode URL manually instead of having readable syntax in the documentation

I think a good solution is

  1. re-encode URL anyway (to remove spaces and encode other chars to URL format)
  2. try to find tag with this ID <tag id="impl-for-Trait-...-link">...</tag> in rustdoc
  3. fallback to existing #link in markdown if we can't find it

@camelid
Copy link
Member

camelid commented Dec 16, 2022

Thinking about it again, I am surprised that rustdoc doesn't encode the comma and space in the URL. We should check what the Markdown spec says to do. cc @GuillaumeGomez

@camelid
Copy link
Member

camelid commented Dec 16, 2022

Regarding (2) and (3) in your list, I think those would be taken care of by just encoding the URL. Please let me know if I misunderstood.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-intra-doc-links Area: Intra-doc links, the ability to link to items in docs by name 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

No branches or pull requests

4 participants