itsscb/cargo
1
0
Fork 0
mirror of https://github.com/rust-lang/cargo.git synced 2025-09-28 11:20:36 +00:00
Code Issues Packages Projects Releases Wiki Activity

Auto merge of #14561 - RalfJung:crates-io-docs, r=weihanglo

Browse Source 
remove reference to incomplete crates.io feature from docs

The cargo docs for the `documentation` field currently are written in a way that makes it sound like if I want to use docs.rs, I can just leave the field empty. However, that is not the case: leaving the field empty will never show a "Documentation" link in the search results, so there's always an unnecessary extra click to go from "type crate name into search" to reaching the docs.

This crates.io limitation is tracked at https://github.com/rust-lang/crates.io/issues/1484. It doesn't really matter whether this is a bug or a missing feature, the point is that cargo docs are misrepresenting what crates.io does in a way that leads to a suboptimal user experience (many crates without "Documentation" link in crates.io search results). Since the suggestion to document what crates.io actually does was rejected (https://github.com/rust-lang/cargo/pull/13660), I suggest we instead stop mentioning this feature at all -- that's still clearly better than mentioning it while it is not yet fully implemented / while it has some significant *undocumented* limitation.
This commit is contained in:
bors 2024-09-18 11:42:26 +00:00
commit 0461165eae
1 changed files with 1 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
src/doc/src/reference/manifest.md
View File

@ -209,9 +209,7 @@ description = "A short description of my package"
### The `documentation` field
The `documentation` field specifies a URL to a website hosting the crate's
documentation. If no URL is specified in the manifest file, [crates.io] will
automatically link your crate to the corresponding [docs.rs] page when the
documentation has been built and is available (see [docs.rs queue]).
documentation.
```toml
[package]
@ -219,8 +217,6 @@ documentation has been built and is available (see [docs.rs queue]).
documentation = "https://docs.rs/bitflags"
```
[docs.rs queue]: https://docs.rs/releases/queue
### The `readme` field
The `readme` field should be the path to a file in the package root (relative