remove reference to incomplete crates.io feature from docs #14561
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
rustbot
added
A-documenting-cargo-itself
weihanglo
approved these changes
Sep 18, 2024
There was a problem hiding this comment.
Agree with you on the removal. It's no harm for people to just set it.
Note that there are other places outside The Cargo Book mentions the same thing: https://rust-lang.github.io/api-guidelines/documentation.html#cargotoml-includes-all-common-metadata-c-metadata
|
@bors r+ |
bors
added
S-waiting-on-bors
|
btw should this close #11777? |
|
☀️ Test successful - checks-actions |
|
My stance on removal was dependent on where the fix was at. After I posted that, we got an update on that at rust-lang/crates.io#1484 (comment). As rust-lang/docs.rs#2533 exists and will hopefully move forward again, I would lean towards reverting this and keeping the documentation. |
|
It is entirely unclear when that will actually land, and then crates.io still needs to be adjusted to make use of it. I don't think docs should be written for some hypothetical future -- even if that future might be here in ~6 months. |
|
FWIW this got reverted in #14562. |
bors
added a commit
to rust-lang-ci/rust
that referenced
this pull request
Sep 20, 2024
Update cargo 16 commits in a9a418d1a22f29e7dfd034e3b93f15657e608a29..eaee77dc1584be45949b75e4c4c9a841605e3a4b 2024-09-15 19:13:12 +0000 to 2024-09-19 21:10:23 +0000 - fix(complete): Harden `--target` completions (rust-lang/cargo#14564) - Cleanup duplicated check-cfg lint logic (rust-lang/cargo#14567) - Revert "remove reference to incomplete crates.io feature from docs" (rust-lang/cargo#14562) - feat: Add custom completer for `cargo help <TAB>` (rust-lang/cargo#14557) - docs(unstable): Expand on completion documentation (rust-lang/cargo#14563) - feat: Add custom completer for `cargo build --example=<TAB>` (rust-lang/cargo#14531) - remove reference to incomplete crates.io feature from docs (rust-lang/cargo#14561) - fix(complete): Fix problems on my machine (rust-lang/cargo#14558) - feat: Add custom completer for completing benchmark names (rust-lang/cargo#14532) - refactor(info): Use the `shell.note` to print the note (rust-lang/cargo#14554) - feat: Add custom completer for completing test names (rust-lang/cargo#14548) - Suggest `cargo info` command in the `cargo search` result (rust-lang/cargo#14537) - feat: Add custom completer for completing target triple (rust-lang/cargo#14535) - feat: Add custom completer for `cargo -Z <TAB>` (rust-lang/cargo#14536) - feat: Add custom completer for completing installed binaries (rust-lang/cargo#14534) - feat: Add custom completer for completing bin names (rust-lang/cargo#14533) r? ghost
RalfJung
pushed a commit
to RalfJung/miri
that referenced
this pull request
Sep 21, 2024
Update cargo 16 commits in a9a418d1a22f29e7dfd034e3b93f15657e608a29..eaee77dc1584be45949b75e4c4c9a841605e3a4b 2024-09-15 19:13:12 +0000 to 2024-09-19 21:10:23 +0000 - fix(complete): Harden `--target` completions (rust-lang/cargo#14564) - Cleanup duplicated check-cfg lint logic (rust-lang/cargo#14567) - Revert "remove reference to incomplete crates.io feature from docs" (rust-lang/cargo#14562) - feat: Add custom completer for `cargo help <TAB>` (rust-lang/cargo#14557) - docs(unstable): Expand on completion documentation (rust-lang/cargo#14563) - feat: Add custom completer for `cargo build --example=<TAB>` (rust-lang/cargo#14531) - remove reference to incomplete crates.io feature from docs (rust-lang/cargo#14561) - fix(complete): Fix problems on my machine (rust-lang/cargo#14558) - feat: Add custom completer for completing benchmark names (rust-lang/cargo#14532) - refactor(info): Use the `shell.note` to print the note (rust-lang/cargo#14554) - feat: Add custom completer for completing test names (rust-lang/cargo#14548) - Suggest `cargo info` command in the `cargo search` result (rust-lang/cargo#14537) - feat: Add custom completer for completing target triple (rust-lang/cargo#14535) - feat: Add custom completer for `cargo -Z <TAB>` (rust-lang/cargo#14536) - feat: Add custom completer for completing installed binaries (rust-lang/cargo#14534) - feat: Add custom completer for completing bin names (rust-lang/cargo#14533) r? ghost
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
The cargo docs for the
documentationfield 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.
Fixes #11777