Skip to content

Commit

Permalink
Auto merge of #14561 - RalfJung:crates-io-docs, r=weihanglo
Browse files Browse the repository at this point in the history
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 rust-lang/crates.io#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 (#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.
  • Loading branch information
bors committed Sep 18, 2024
2 parents 7f44292 + 1735917 commit 0461165
Showing 1 changed file with 1 addition and 5 deletions.
6 changes: 1 addition & 5 deletions src/doc/src/reference/manifest.md
Original file line number Diff line number Diff line change
Expand Up @@ -209,18 +209,14 @@ 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]
# ...
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
Expand Down

0 comments on commit 0461165

Please sign in to comment.