cargo
cargo copied to clipboard
rust-lang
clarify default behavior of `documentation` field
Cc https://github.com/rust-lang/cargo/issues/11777, https://github.com/rust-lang/crates.io/issues/1484
r? @ehuss
rustbot has assigned @ehuss. They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.
Use r? to explicitly pick a reviewer
For myself, I feel like its a bug in the system that we have to add so much nuance here. If that bug isn't being fixed, should we just not reference this and encourage people to set the links?
Yea, I would agree this seems like weird bug to document. I'm also a little confused, as it seems like the accepted solution should be relatively trivial (something like documentation.or_else(|| format!("https://docs.rs/{name}/latest/{name}")) in the search code).
See https://github.com/rust-lang/crates.io/issues/1484, apparently what the crate page does is a lot more complicated than documentation.or_else and involves querying the docs.rs API to check if the crate is actually documented there.
My comment was based on https://github.com/rust-lang/crates.io/issues/1484#issuecomment-885620320, which says that the search results should not do that query, and instead just always link to the latest version if the documentation field is not specified. That might cause an issue when the docs are not yet ready, or failed to build, but would be no different than if the user specified the documentation field manually.
If we agree on seeing a fix on crates.io or other services, should this be closed?
Close as it is more like a buggy behavior in crates.io that we don't want to document. Thanks everyone for the discussion.
Does the cargo team define whether this is a bug in crates.io? That seems like a crates.io decision to me. https://github.com/rust-lang/crates.io/issues/1484 is marked as "enhancement".
Meanwhile, we are doing our users a disservice by having documentation that actively contradicts reality.
Even if this is a bug in crates.io, it is clearly a long-standing issue and hard to fix. So telling users in the cargo docs that they can just leave the docs field empty if they use docs.rs (which is effectively what the docs are doing) is not helping.
I have to say I am quite disappointed with how this has been handled -- we have docs that actively confuse users and lead them in the wrong direction, and instead of trying to fix this we're squabbling about whether this is a bug or not?
It would be better to not mention this crates.io feature at all then: https://github.com/rust-lang/cargo/pull/14561.
Meanwhile, we are doing our users a disservice by having documentation that actively contradicts reality.
Its fairly close to reality
Even if this is a bug in crates.io, it is clearly a long-standing issue and hard to fix. So telling users in the cargo docs that they can just leave the docs field empty if they use docs.rs (which is effectively what the docs are doing) is not helping.
While its long standing, there has been recent progress to fixing it. iiuc the blocker for fixing it is on docs.rs's side and the PR for that was started this summer (rust-lang/docs.rs#2533).
I mentioned that I was fine with removal if this was going to the status quo but that doesn't appear to be the case, so I lean towards keeping the documentation.
It's far enough from reality to cause actual problems: many crates have no "Documentation" link in the crates.io search results, adding an entirely unnecessary extra click for the quite common flow of "go search some crate to find its docs". I think these docs (and the others that should still be fixed) take a good chunk of responsibility for that.
If the concern is about browsing crates.io, at this point, it would be a major undertaking to get people to notice the documentation change to specify package.documentation and for people to act on it. It doesn't seem worthwhile to make that shift when we'll just switch back again.