Very slight `cargo add` documentation improvements #11033

buggymcbugfix · 2022-08-30T20:08:56Z

As discussed in rust-lang/book#3331, a quick explanation of the Features part of the message that gets printed to stdout when adding some dependency.

Consider the following example:

cargo add my-crate
    Updating crates.io index
      Adding my-crate v0.1.0 to dependencies.
             Features:
             + foo
             - bar

It was not clear to me what +foo and -bar meant until @carols10cents' kindly explained it to me. Hopefully the documentation now clarifies this.

TODO:

Run ./build-man.sh

rust-highfive · 2022-08-30T20:08:59Z

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @ehuss (or someone else) soon.

Please see the contribution instructions for more information.

buggymcbugfix · 2022-08-30T20:16:30Z

Oops, looks like I edited the wrong file. Looking into this.

EDIT: resolved.

src/doc/src/commands/cargo-add.md

epage · 2022-08-30T20:34:34Z

Oops, looks like I edited the wrong file. Looking into this.

EDIT: resolved.

This is a common problem. We should consider if there are ways to better point users to what to edit

buggymcbugfix · 2022-08-30T20:49:15Z

This is a common problem. We should consider if there are ways to better point users to what to edit

Yes, putting all the generated files into a build or generated directory instead of src would have made it way more obvious to me. Alternatively, a comment at the top of the file along the lines of  would have done the job too and might be less invasive than moving stuff around?

Btw I am extremely touched that you consider my mistake an opportunity to improve the contribution process!

This refers to the `Features` part of the message that gets printed to stderr after successfully adding some dependency, e.g.: ``` cargo add my-crate Updating crates.io index Adding my-crate v0.1.0 to dependencies. Features: + foo - bar ``` This tells us that the `foo` feature is enabled and `bar` is disabled.

epage · 2022-08-30T21:50:09Z

@bors r+

Thanks!

bors · 2022-08-30T21:50:10Z

📌 Commit 9c8a8ea has been approved by epage

It is now in the queue for this repository.

bors · 2022-08-30T21:50:16Z

⌛ Testing commit 9c8a8ea with merge f75aee0...

bors · 2022-08-30T22:32:57Z

☀️ Test successful - checks-actions
Approved by: epage
Pushing f75aee0 to master...

epage · 2022-08-31T20:53:25Z

RE Improving the experience

I have two ideas:

Put in a .ignore file to ignore the generated output so if someone runs ripgrep to find the documentation, they'll only get the source back
Prefix the output directories with _ to signify they are special

epage · 2022-08-31T21:07:39Z

Hmm, directory rename won't work as well as I expected because I forgot how things are laid out.

The goal is to help new (and existing) users more quickly find the appropriate files to edit (like in rust-lang#11033). The main downside is for someone trying to find output to verify what it looks like, a simple search won't turn up results but there are other ways around that (`--no-ignore`, `git status` after doing a man generation, etc).

chore: Don't show genned docs in ripgrep The goal is to help new (and existing) users more quickly find the appropriate files to edit (like in #11033). The main downside is for someone trying to find output to verify what it looks like, a simple search won't turn up results but there are other ways around that (`--no-ignore`, `git status` after doing a man generation, etc).

8 commits in 4ed54cecce3ce9ab6ff058781f4c8a500ee6b8b5..646e9a0b9ea8354cc409d05f10e8dc752c5de78e 2022-08-27 18:41:39 +0000 to 2022-09-02 14:29:28 +0000 - Support inheriting jobserver fd for external subcommands (rust-lang/cargo#10511) - refactor(cli): Lazy load config (rust-lang/cargo#11029) - chore: Don't show genned docs in ripgrep (rust-lang/cargo#11040) - Document private items for Cargo and publish under contributor guide (rust-lang/cargo#11019) - Add names to CI jobs (rust-lang/cargo#11039) - Rework test error handling (rust-lang/cargo#11028) - Very slight `cargo add` documentation improvements (rust-lang/cargo#11033) - Update compiling requirements. (rust-lang/cargo#11030)

Update cargo 8 commits in 4ed54cecce3ce9ab6ff058781f4c8a500ee6b8b5..646e9a0b9ea8354cc409d05f10e8dc752c5de78e 2022-08-27 18:41:39 +0000 to 2022-09-02 14:29:28 +0000 - Support inheriting jobserver fd for external subcommands (rust-lang/cargo#10511) - refactor(cli): Lazy load config (rust-lang/cargo#11029) - chore: Don't show genned docs in ripgrep (rust-lang/cargo#11040) - Document private items for Cargo and publish under contributor guide (rust-lang/cargo#11019) - Add names to CI jobs (rust-lang/cargo#11039) - Rework test error handling (rust-lang/cargo#11028) - Very slight `cargo add` documentation improvements (rust-lang/cargo#11033) - Update compiling requirements. (rust-lang/cargo#11030)

The goal is to help new (and existing) users more quickly find the appropriate files to edit (like in rust-lang#11033). The main downside is for someone trying to find output to verify what it looks like, a simple search won't turn up results but there are other ways around that (`--no-ignore`, `git status` after doing a man generation, etc).

rust-highfive assigned ehuss Aug 30, 2022

rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Aug 30, 2022

epage reviewed Aug 30, 2022

View reviewed changes

src/doc/src/commands/cargo-add.md Outdated Show resolved Hide resolved

buggymcbugfix force-pushed the buggymcbugfix/cargo-add-docs branch 2 times, most recently from f5f8c5f to 7d7e0fa Compare August 30, 2022 20:30

epage reviewed Aug 30, 2022

View reviewed changes

src/doc/src/commands/cargo-add.md Outdated Show resolved Hide resolved

buggymcbugfix force-pushed the buggymcbugfix/cargo-add-docs branch 2 times, most recently from 0853879 to cf4fe85 Compare August 30, 2022 20:56

buggymcbugfix force-pushed the buggymcbugfix/cargo-add-docs branch from cf4fe85 to 9c8a8ea Compare August 30, 2022 20:59

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Aug 30, 2022

bors merged commit f75aee0 into rust-lang:master Aug 30, 2022

epage mentioned this pull request Aug 31, 2022

chore: Don't show genned docs in ripgrep #11040

Merged

weihanglo mentioned this pull request Sep 5, 2022

Update cargo rust-lang/rust#101460

Merged

ehuss added this to the 1.65.0 milestone Sep 21, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Very slight `cargo add` documentation improvements #11033

Very slight `cargo add` documentation improvements #11033

buggymcbugfix commented Aug 30, 2022 •

edited

Loading

rust-highfive commented Aug 30, 2022

buggymcbugfix commented Aug 30, 2022 •

edited

Loading

epage commented Aug 30, 2022

buggymcbugfix commented Aug 30, 2022

epage commented Aug 30, 2022

bors commented Aug 30, 2022

bors commented Aug 30, 2022

bors commented Aug 30, 2022

epage commented Aug 31, 2022

epage commented Aug 31, 2022

Very slight cargo add documentation improvements #11033

Very slight cargo add documentation improvements #11033

Conversation

buggymcbugfix commented Aug 30, 2022 • edited Loading

rust-highfive commented Aug 30, 2022

buggymcbugfix commented Aug 30, 2022 • edited Loading

epage commented Aug 30, 2022

buggymcbugfix commented Aug 30, 2022

epage commented Aug 30, 2022

bors commented Aug 30, 2022

bors commented Aug 30, 2022

bors commented Aug 30, 2022

epage commented Aug 31, 2022

epage commented Aug 31, 2022

Very slight `cargo add` documentation improvements #11033

Very slight `cargo add` documentation improvements #11033

buggymcbugfix commented Aug 30, 2022 •

edited

Loading

buggymcbugfix commented Aug 30, 2022 •

edited

Loading