Skip to content

Commit

Permalink
Clarify note in example (#15054)
Browse files Browse the repository at this point in the history
### What does this PR try to resolve?

I was reading the docs to see how to specify a version to use from a git
dependency, and came across this section and got really confused as I
did not know what `N.B.` meant so the following did not read well for
me: `N.B. that if ...`. I had to look it up and then realized that I had
wasted time that did not need to be wasted. Thus this PR aims to prevent
the time of future readers from being wasted.

### How should we test and review this PR?

Try to read aloud the old version and the new one, as well as the given
alternatives to see which would make most sense to the largest number of
people.

### Additional information

A simple fix would be to just remove "that" as this reads better: `N.B.
if a version doesn't match, Cargo will fail to compile!`

#### Other variations
* `Note that if a version doesn't match, Cargo will fail to compile!`
- might be confused as `Notice that if a version doesn't match, Cargo
will fail to compile!`
* Move the comment out to a reworded sentence right below the code block
and perhaps also link to the [`The role of the version
key`](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#the-role-of-the-version-key)
section above which clearly states:
> The version key does not affect which commit is used when Cargo
retrieves the git dependency, but Cargo checks the version information
in the dependency’s Cargo.toml file against the version key and raises
an error if the check fails.
  • Loading branch information
weihanglo authored Jan 12, 2025
2 parents 5408cc2 + 31208bd commit f15df8f
Showing 1 changed file with 1 addition and 1 deletion.
2 changes: 1 addition & 1 deletion src/doc/src/reference/specifying-dependencies.md
Original file line number Diff line number Diff line change
Expand Up @@ -390,7 +390,7 @@ bitflags = { path = "my-bitflags", version = "1.0" }
# version 1.0 from crates.io when published.
smallvec = { git = "https://github.com/servo/rust-smallvec.git", version = "1.0" }

# N.B. that if a version doesn't match, Cargo will fail to compile!
# Note: if a version doesn't match, Cargo will fail to compile!
```

One example where this can be useful is when you have split up a library into
Expand Down

0 comments on commit f15df8f

Please sign in to comment.