Do not mention a non-existing default of crates.io

[Ekleog]

I just published a new crate on crates.io, and it does not appear to link the documentation at all when no documentation field is provided.

Example: https://crates.io/crates/kine/0.1.0

[rustbot]

r? @ehuss

(rustbot has picked a reviewer for you, use r? to override)

[Ekleog]

Hmm… I'm pretty sure the ICE is not actually related to the documentation-only change in this PR 😅

[Muscraft]

Hmm… I'm pretty sure the ICE is not actually related to the documentation-only change in this PR 😅

You are correct! In another PR, this was said:

CI will be blocked until rust-lang/rust#107688 lands in nightly.

[taiki-e]

it does not appear to link the documentation at all

It appears to be working now.

(According to the docs.rs build log, it appears that the document was built a few minutes after you opened this PR.)

[weihanglo]

Given the link eventually shows on crates.io after the doc was built, does that the original statement still stands and this PR can be closed?

[Ekleog]

Ooh so do you mean that the process here is:

1. docs.rs compiles the crate,
2. it confirms to crates.io that it compiled the crate correctly,
3. crates.io adds the link to the page?

That's possible, but my guess would more be along the lines of "I added the link in 0.1.1 and crates.io picked it up from that".

To support this statement, a random old crate has no documentation link but does have a docs.rs page.

TBH I'm not sure what behavior is supposed to be. If you're sure that it actually will add the link and it just didn't do so at the time of the foo crate being published, then I'll be happy to edit this PR to instead mention the fact that one may need to wait for a few hours before the link actually appears :)

[epage]

To support this statement, a random old crate has no documentation link but does have a docs.rs page.

Go back far enough and docs.rs was not an official service but was something someone was doing because they thought it was important. It looks like foo is old enough for that.

[weihanglo]

TBH I'm not sure what behavior is supposed to be.

Found it! The piece of code in crates.io is here. Seems like the JavaScript code fetches build.json on-the-fly. I am fine with a little more words explaining that.

[Ekleog]

Hmm ok so another way I see of fixing this would be to actually make crates.io in line with the current doc. WDYT about having a https://github.com/rust-lang/crates.io/blob/38cd37469fe88c18814c3c348444da297fec49e8/app/models/version.js#L158 actually returning https://docs.rs/${this.crateName}/${this.num} instead of null if no link was found? It'd both fix old crates and avoid the question altogether.

[ehuss]

I think that would cause issues if the docs are not available. A user clicking on the link would get an error if the docs weren't available. You can check with the crates.io and docs.rs teams to see if that's a change they would want to do, but it is not something we would be able to answer here.

[ehuss]

@rustbot author

[weihanglo]

Going to close due to inactivity. This confusion may be fixed on crates.io/docs.rs side, and we might want to avoid documenting implementation details of other projects. That being said, if you have more improvement on this topic, feel free to open a new issue/PR.

[ehuss]

Just a heads up, I nominated this and #11777 for discussion (though I probably should have actually put labels on them). It's not clear to me on how we should actually proceed here.

At least in the short term, we could clarify this text such as: "link your crate to the corresponding [docs.rs] page when the documentation is available." or something like that.

But there is a longer-term decision about whether or not we should recommend specifying the documentation field. Issues like #11777 also show that there are other problems around how crates.io displays it, and I am skeptical that can be easily fixed. If crates.io wants to ensure that the implicit docs.rs documentation link only works if the documentation actually exists, then that causes issues for the search results page. I think it is unlikely it will have client-side queries in the search page. And to implement that on the server side would probably require more backend services, which seems like quite a bit of work and hassle for something relatively minor.