I was reading through the Rust Guide (hopefully looking to learn some Rust), and I figured it would be a good idea to open a pull request with some of the errata I noticed along the way. Most of the changes are pretty mundane, but there are a couple that might raise a bit of discussion.
### Punctuation outside of 'key term' quotes
This is something that was inconsistent in the Guide. While the convention in American English is to place punctuation immediately following a quotation mark *inside* the quotation mark, it seems strange to do this with 'key terms', considering they are not a true quotation.
### Changed comment placement in 17.2 code block
This is what the code block in [17.2 — Ownership, borrowing, and lifetimes](http://doc.rust-lang.org/guide.html#ownership,-borrowing,-and-lifetimes) looks like in fullscreened Safari 8:
Some of the comments extend *just* too far, causing them to bleed into the next line, so I moved a few of them above the relevant lines of code to avoid this.
- Various grammatical changes
- Place punctuation outside of key term quotes
- Change comment placement in 17.2 code block
- Replace double hyphens with en dashes
This commit is part of a series that introduces a `std::thread` API to
replace `std::task`.
In the new API, `spawn` returns a `JoinGuard`, which by default will
join the spawned thread when dropped. It can also be used to join
explicitly at any time, returning the thread's result. Alternatively,
the spawned thread can be explicitly detached (so no join takes place).
As part of this change, Rust processes now terminate when the main
thread exits, even if other detached threads are still running, moving
Rust closer to standard threading models. This new behavior may break code
that was relying on the previously implicit join-all.
In addition to the above, the new thread API also offers some built-in
support for building blocking abstractions in user space; see the module
doc for details.
Closes#18000
[breaking-change]
In US english, "that" is used in restrictive clauses in place of
"which", and often affects the meaning of sentences.
In UK english and many dialects, no distinction is
made.
While Rust devs want to avoid unproductive pedanticism, it is worth at
least being uniform in documentation such as:
http://doc.rust-lang.org/std/iter/index.html
and also in cases where correct usage of US english clarifies the
sentence.
In US english, "that" is used in restrictive clauses in place of
"which", and often affects the meaning of sentences.
In UK english and many dialects, no distinction is
made.
While Rust devs want to avoid unproductive pedanticism, it is worth at
least being uniform in documentation such as:
http://doc.rust-lang.org/std/iter/index.html
and also in cases where correct usage of US english clarifies the
sentence.
Using `and` here instead of `but` sounds better to me, as but makes it sound like an item which is still under active development shouldn't normally require more testing, but this one does - or something like that :-)
@steveklabnik?
The reason given didn't make any sense when I read it when reading through the docs. I think this is more clear. Please let me know it is also more correct.
As-is, there's no indication that the code examples pop out into a window that runs on `play.rust-lang.org` until you mouse over them. I managed to get to section 4 of the guide before realizing you could do this since it didn't occur to me to mouse over the example text.
cc @rose since we went through the tutorial together and I think it wasn't obvious to her either.
This breaks code that referred to variant names in the same namespace as
their enum. Reexport the variants in the old location or alter code to
refer to the new locations:
```
pub enum Foo {
A,
B
}
fn main() {
let a = A;
}
```
=>
```
pub use self::Foo::{A, B};
pub enum Foo {
A,
B
}
fn main() {
let a = A;
}
```
or
```
pub enum Foo {
A,
B
}
fn main() {
let a = Foo::A;
}
```
[breaking-change]
As a new user, I spent a while confused when flycheck told me the code sample I'd typed in was invalid. I ended up figuring out some of what comes after the code sample more painfully by myself because there was no indication that it was broken in the text beforehand. This one line change makes it clear that the code following it is an experiment that may not work rather than something to assume just works.
This removes some leftover line-numbering cruft from elided error examples and brings some minor clarifications.
I’m not super happy about the ‘we cannot have two mutable pointers that point to the same memory’ wording (to the best of my understanding we can’t even have one mutable and one immutable), but other attempts to word this were derailing the flow a bit too much.
I think it helps to show that the variables introduced in match blocks are indeed independent from the matched variable `x` (especially when `x` is still reachable inside those blocks and might be useful), so this renames them accordingly. Maybe some linter (or language-level warning?) will eventually warn about shadowing `x` in such cases. ;)
I’m not super happy about the matching-on-range example, as it’s too contrived (`e` and `x` are exactly the same here), but I couldn’t come up with something both simple and non-redundant.
https://github.com/rust-lang/rfcs/pull/221
The current terminology of "task failure" often causes problems when
writing or speaking about code. You often want to talk about the
possibility of an operation that returns a Result "failing", but cannot
because of the ambiguity with task failure. Instead, you have to speak
of "the failing case" or "when the operation does not succeed" or other
circumlocutions.
Likewise, we use a "Failure" header in rustdoc to describe when
operations may fail the task, but it would often be helpful to separate
out a section describing the "Err-producing" case.
We have been steadily moving away from task failure and toward Result as
an error-handling mechanism, so we should optimize our terminology
accordingly: Result-producing functions should be easy to describe.
To update your code, rename any call to `fail!` to `panic!` instead.
Assuming you have not created your own macro named `panic!`, this
will work on UNIX based systems:
grep -lZR 'fail!' . | xargs -0 -l sed -i -e 's/fail!/panic!/g'
You can of course also do this by hand.
[breaking-change]
Some minor wording fixes to the Closures chapter; my brain tripped a few times when reading it, so I tried to come up with something a bit smoother. I’m not a native speaker, so please do review this critically.
Explain that Rust has different pointer types because there is a
tradeoff between flexibility and efficiency. Motivate boxes as
fixed-size containers of variable-sized objects. Clarify that Box and Rc
are pointer types that you deref with * just like references. Stick to
explaining the semantics and avoid implementation details. Scope isn't
the most accurate framework to think about deallocation (since you
return boxes and otherwise move values out of scopes); it's more "when
the value is done being used," i.e., lifetime. Provide a connection
between Rust's pointer types by locating them on a flexibiltiy /
performance scale. Explain the compiler can't statically analyze
lifetimes with multiple owners; hence the need for (runtime) reference
counting.
Explain the primary disadvantage of garbage collection is runtime
overhead and unpredictable pauses. Elucidate where the name "race
condition" comes from. Emphasize that Rust can guarantee your code is
free of race conditions and other memory errors, with no runtime
overhead.
cc @steveklabnik
Explain the primary disadvantage of garbage collection is runtime
overhead and unpredictable pauses. Elucidate where the name "race
condition" comes from. Emphasize that Rust can guarantee your code is
free of race conditions and other memory errors, with no runtime
overhead.
The array is the fundamental concept; vectors are growable arrays, and
slices are views into either. Show common array ops up front: length
and iteration. Mention arrays are immutable by default. Highlight
definite initialization and bounds-checking as safety features. Show
that you only need a type suffix on one element of initializers.
Explain that vectors are a value-add library type over arrays, not a
fundamental type; show they have the same "interface." Motivate slices
as efficient views into arrays; explain you can slice vectors, Strings,
&str because they're backed by arrays.
