doc: Improve example of using the links field #10728
Merged
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
clearer example
|
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
added
the
S-waiting-on-review
epage
reviewed
Jun 3, 2022
| @@ -364,7 +364,8 @@ script guide. | |||
| ```toml | |||
| [package] | |||
| # ... | |||
| links = "foo" | |||
| # this package links with a native library called "git2", e.g. "libgit2.a" on Linux | |||
| links = "git2" | |||
| ``` | |||
There was a problem hiding this comment.
Nit: I think I'd prefer to instead say
For example, to link against the native library `git2` (e.g. `libgit2.a` on Linux):
```toml
```
- It makes the example more directly related to what an end-user will do
- It doesn't unintentionally reinforce to users to repeat what they are commenting about in comments
There was a problem hiding this comment.
Putting the note outside of the TOML sounds good (also for consistency with the rest of the examples).
I would caution on the exact wording, as saying "to link against…" might be misleading since adding links doesn't actually cause a library to be linked. I would lean more towards the proposed text ("this package links with a…"), or maybe a slight modification like "links indicates that the package links with a …".
There was a problem hiding this comment.
OK, I have revised this a bit. It now says
For example, a crate that links a native library called "git2" (e.g. `libgit2.a`
on Linux) may specify:
```toml
links = "git2"
```
Remove comment from example toml to prose.
|
Thanks! @bors r+ |
|
📌 Commit c586652 has been approved by |
bors
added
S-waiting-on-bors
|
☀️ Test successful - checks-actions |
arlosi
added a commit
to arlosi/rust
that referenced
this pull request
Jun 17, 2022
4 commits in 4d92f07f34ba7fb7d7f207564942508f46c225d3..8d42b0e8794ce3787c9f7d6d88b02ae80ebe8d19 2022-06-10 01:11:04 +0000 to 2022-06-17 16:46:26 +0000 - Use specific terminology for sparse HTTP-based registry (rust-lang/cargo#10764) - chore: Upgrade to clap 3.2 (rust-lang/cargo#10753) - Improve testing framework for http registries (rust-lang/cargo#10738) - doc: Improve example of using the links field (rust-lang/cargo#10728)
matthiaskrgr
added a commit
to matthiaskrgr/rust
that referenced
this pull request
Jun 18, 2022
Update cargo 4 commits in 4d92f07f34ba7fb7d7f207564942508f46c225d3..8d42b0e8794ce3787c9f7d6d88b02ae80ebe8d19 2022-06-10 01:11:04 +0000 to 2022-06-17 16:46:26 +0000 - Use specific terminology for sparse HTTP-based registry (rust-lang/cargo#10764) - chore: Upgrade to clap 3.2 (rust-lang/cargo#10753) - Improve testing framework for http registries (rust-lang/cargo#10738) - doc: Improve example of using the links field (rust-lang/cargo#10728)
matthiaskrgr
added a commit
to matthiaskrgr/rust
that referenced
this pull request
Jun 18, 2022
Update cargo 4 commits in 4d92f07f34ba7fb7d7f207564942508f46c225d3..8d42b0e8794ce3787c9f7d6d88b02ae80ebe8d19 2022-06-10 01:11:04 +0000 to 2022-06-17 16:46:26 +0000 - Use specific terminology for sparse HTTP-based registry (rust-lang/cargo#10764) - chore: Upgrade to clap 3.2 (rust-lang/cargo#10753) - Improve testing framework for http registries (rust-lang/cargo#10738) - doc: Improve example of using the links field (rust-lang/cargo#10728)
matthiaskrgr
added a commit
to matthiaskrgr/rust
that referenced
this pull request
Jun 18, 2022
Update cargo 4 commits in 4d92f07f34ba7fb7d7f207564942508f46c225d3..8d42b0e8794ce3787c9f7d6d88b02ae80ebe8d19 2022-06-10 01:11:04 +0000 to 2022-06-17 16:46:26 +0000 - Use specific terminology for sparse HTTP-based registry (rust-lang/cargo#10764) - chore: Upgrade to clap 3.2 (rust-lang/cargo#10753) - Improve testing framework for http registries (rust-lang/cargo#10738) - doc: Improve example of using the links field (rust-lang/cargo#10728)
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.
"foo"doesn't really help say what this is.