Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Very slight cargo add documentation improvements #11033

Merged
merged 1 commit into from
Aug 30, 2022
Merged

Very slight cargo add documentation improvements #11033

merged 1 commit into from
Aug 30, 2022

Conversation

buggymcbugfix
Copy link
Contributor

@buggymcbugfix buggymcbugfix commented Aug 30, 2022 •
edited
Loading

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
Copy link

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.

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

buggymcbugfix commented Aug 30, 2022 •
edited
Loading

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

EDIT: resolved.

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

epage commented Aug 30, 2022

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
Copy link
Contributor Author

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 <!-- This file is generated, you want to edit the corresponding file in the `man` directory! --> 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!

@buggymcbugfix buggymcbugfix force-pushed the buggymcbugfix/cargo-add-docs branch 2 times, most recently from 0853879 to cf4fe85 Compare August 30, 2022 20:56
@buggymcbugfix
Document cargo-add's feature message
9c8a8ea 
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
Copy link
Contributor

epage commented Aug 30, 2022

@bors r+

Thanks!

@bors
Copy link
Contributor

bors commented Aug 30, 2022

📌 Commit 9c8a8ea has been approved by epage

It is now in the queue for this repository.

@bors 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
Copy link
Contributor

bors commented Aug 30, 2022

⌛ Testing commit 9c8a8ea with merge f75aee0...

@bors
Copy link
Contributor

bors commented Aug 30, 2022

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

@bors bors merged commit f75aee0 into rust-lang:master Aug 30, 2022
@epage
Copy link
Contributor

epage commented Aug 31, 2022

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
Copy link
Contributor

epage commented Aug 31, 2022

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

epage added a commit to epage/cargo that referenced this pull request Aug 31, 2022
@epage
chore: Don't show genned docs in ripgrep
ffaf4b1 
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).
@epage epage mentioned this pull request Aug 31, 2022
Merged
bors added a commit that referenced this pull request Sep 1, 2022
@bors
Auto merge of #11040 - epage:confusion, r=ehuss
d2ea9af 
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).
weihanglo added a commit to rust-lang/rust that referenced this pull request Sep 5, 2022
@weihanglo
Update cargo
11e66e1 
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)
@weihanglo weihanglo mentioned this pull request Sep 5, 2022
Merged
bors added a commit to rust-lang-ci/rust that referenced this pull request Sep 5, 2022
@bors
Auto merge of rust-lang#101460 - rust-lang:update-cargo, r=ehuss
676afc5 
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)
@ehuss ehuss added this to the 1.65.0 milestone Sep 21, 2022
Hezuikn pushed a commit to Hezuikn/cargo that referenced this pull request Sep 22, 2022
@epage @Hezuikn
chore: Don't show genned docs in ripgrep
4782834 
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).
Hezuikn pushed a commit to Hezuikn/cargo that referenced this pull request Sep 22, 2022
@epage @Hezuikn
chore: Don't show genned docs in ripgrep
cd31fc5 
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).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@epage epage epage left review comments

Assignees

@ehuss ehuss

Labels
S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion.
Projects
None yet
Milestone
1.65.0
Development

Successfully merging this pull request may close these issues.
5 participants
@buggymcbugfix @rust-highfive @epage @bors @ehuss