No documentation field vs. linking to docs.rs

[nihaals]

The cargo reference for the documentation field says:

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

To me, when I published my first crate, this implied that not including the documentation field is fine for most crates as it is equivalent to setting it to the crate's docs.rs page and so I didn't include it. After publishing the crate, I noticed a few unexpected behaviours:

1. In search results, the crate has no Documentation link
2. While it is in the docs.rs queue, no Documentation header is shown on the crate's page
3. After docs.rs had built the version, when going to the crate's page, there would be a delay before the Documentation header would show up

When I noticed 1. I checked some other crates and noticed they still linked to the docs.rs page. So clearly something was different. I went on the Git repo and noticed that almost every crate I checked had documentation = "https://docs.rs/<crate name>". I then also noticed that this correlated with the missing Documentation link in search results.

When I added the field and published a new version, I noticed another interesting inconsistency: in search results, the Documentation link linked to https://docs.rs/<crate name>, while on the crate's page, it linked to https://docs.rs/<crate name>/<version>/. Also, while the crate was in the docs.rs queue, the Documentation header on the crate's page linked to https://docs.rs/<crate name>, which was then replaced with the version specific URL after it had been built (which made sense although was still unexpected as I didn't see any special-casing in the documentation I read).

As Cargo.toml isn't purely for crates.io, I don't think all these nuances necessarily need to be documented in the cargo reference, but maybe they should be documented somewhere and linked there (as I was guided to that page from the publishing guide or maybe crates.io could more closely match not providing a documentation field with providing one that links to the docs.rs page.

After publishing this crate I've essentially learnt to use documentation = "https://docs.rs/<crate name>" for every crate I publish for:

• Faster loading of the documentation link on the crate page
• More consistent loading of the documentation link on the crate page
• A link to the documentation in search results
• To be explicit to help with registries other than crates.io

As there are many crates with no documentation field set, possibly due to the cargo reference page and it initially seeming to work well enough, should crates.io try to make these act more similarly?