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

Documentation for documentation field is misleading #11777

Open
RalfJung opened this issue Feb 27, 2023 · 3 comments · Fixed by #14561
Open

Documentation for documentation field is misleading #11777

RalfJung opened this issue Feb 27, 2023 · 3 comments · Fixed by #14561
Labels
A-documenting-cargo-itself Area: Cargo's documentation S-blocked-external Status: ❌ blocked on something out of the direct control of the Cargo project, e.g., upstream fix

Comments

@RalfJung
Copy link
Member

The docs for the documentation field say

If no URL is specified in the manifest file, crates.io will automatically link your crate to the corresponding docs.rs page.

This sounds as if setting no URL is equivalent to setting the docs.rs URL. That is however not the case: in the crates.io search result list, the "Documentation" link will only show up if documentation is explicitly set in the toml file.

I am not sure if this is a bug in the cargo docs or the crates.io frontend, but it is certainly surprising.

@epage
Copy link
Contributor

epage commented Feb 27, 2023

Seeing as the individual crate pages will list documentation, I would personally chalk this up as a crates.io bug.

From #11685, my suspicion is that this is either an optimization or an oversight. Apparently, adding the docs.rs link to the crate's page is done via Javascript and I imagine doing that for every crate on a search page might be a bit much.

bors added a commit that referenced this issue May 16, 2023
…nglo

docs: Clarify that crates.io doesn't link to docs.rs right away.

This implements the suggestion in #11685 (comment) to help clarify the confusion about the documentation link not appearing on crates.io.

There may be more to follow up here, perhaps with changes on crates.io or docs.rs, to help with some of the confusion. For example, #11777, or changing crates.io to always link to docs.rs, and have docs.rs provide better error pages when docs aren't available. This is just intended as a short-term fix to address some of the confusion.
bors added a commit that referenced this issue May 16, 2023
…nglo

docs: Clarify that crates.io doesn't link to docs.rs right away.

This implements the suggestion in #11685 (comment) to help clarify the confusion about the documentation link not appearing on crates.io.

There may be more to follow up here, perhaps with changes on crates.io or docs.rs, to help with some of the confusion. For example, #11777, or changing crates.io to always link to docs.rs, and have docs.rs provide better error pages when docs aren't available. This is just intended as a short-term fix to address some of the confusion.
@heisen-li
Copy link
Contributor

@rustbot label A-documenting-cargo-itself

@rustbot rustbot added the A-documenting-cargo-itself Area: Cargo's documentation label Apr 9, 2024
@weihanglo weihanglo added the S-blocked-external Status: ❌ blocked on something out of the direct control of the Cargo project, e.g., upstream fix label Apr 10, 2024
@RalfJung
Copy link
Member Author

This should be reopened since #14562 got reverted.

@weihanglo weihanglo reopened this Sep 19, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-documenting-cargo-itself Area: Cargo's documentation S-blocked-external Status: ❌ blocked on something out of the direct control of the Cargo project, e.g., upstream fix
Projects
None yet
Development

Successfully merging a pull request may close this issue.

5 participants