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

Implement the documented behavior of defaulting to docs.rs links for people with XHR blockers too #6060

Closed
wants to merge 1 commit into from

Conversation

Ekleog
Copy link

@Ekleog Ekleog commented Feb 10, 2023

Hey! So before anything: I don't know if this is something you actually want.

I've just noticed that the documented-on-the-cargo-book behavior of defaulting to docs.rs links does not actually work for people who have cross-site XHR blockers, whereas if people manually add the docs.rs link (an operation that should be a no-op according to the cargo book), it does get displayed.

I don't really know javascript, but my understanding is making this change makes things work for everyone, to the cost of having broken docs.rs links when the docs.rs build failed.

Honestly I don't think linking a broken docs.rs build would be a problem (it's actually good indication that the user might not want to use the crate, if the build is broken and the crate did not provide an alternate documentation link). However, I don't have really strong opinions on this, and wanted to get your thoughts.

Context: rust-lang/cargo#11685; I've been thinking for now a few years that crates that did not provide a documentation link had no link on crates.io and wondering why they didn't make the effort of doing so… to the point that I tried submitting a PR to the docs when I noticed this written in the cargo docs. Sure it's my fault, but hopefully the proposed behavior would be more user-friendly to other people who forgot to check that because everything else on crates.io works fine with XHR blockers :)

@Turbo87
Copy link
Member

Turbo87 commented Feb 10, 2023

I don't think this is a tradeoff we should make. The number of people that block regular XHRs (vs. having an adblocker) is tiny compared to the number of people that would potentially see broken or unintentional documentation links.

I'll wait a few days for the rest of the team to chime in though.

@Ekleog
Copy link
Author

Ekleog commented Feb 10, 2023

👍 Out of curiosity, do you have any sort of metrics regarding what proportion of doc links are broken? (Or I can try to gather some if you want)
Basically I don't think I ever noticed any issue with it personally, and I've always fallen back to searching docs.rs for the package docs when there was no link on crates.io (which, granted, was significantly more often for me than for other people), so I think my experience was roughly what people would have (without the manual step) with this PR

@Turbo87 Turbo87 closed this Jan 29, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
Archived in project
Development

Successfully merging this pull request may close these issues.

2 participants