"Truth passes, success `panic!`s" seems to be a typo. The closest fix would be something like "Success passes, failure `panic!`s" but to me a "comparison failure" suggests that we couldn't compare the two values at all, not that we could successfully compare them and that the result was non-equality. So I opted to rewrite the paragraph a bit. If there's a better alternative please let me know.
r? @steveklabnik
The paper from which this example was taken made the mistake of assuming
that all five philosophers are men. This is a hypothetical
example--there are no actual philosophers eating spaghetti--so there is
no good reason to make this assumption. Since women make up about half
of the human population, all things being equal, women should represent
about half of the philosophers. However, because this mistake has stood
since 1985, I have changed *all* of the pronouns to be female, to make
up for lost time. If someone would like to revert this patch or switch
to neutral pronouns after 30 years, feel free to set your alarm clock
for 2045.
This adds strictly more information to the source files and reduces the need for customized tooling to render the book. (While this should not change the output of _rustbook_, it is very useful when rendering the sources with external tools like Pandoc.)
This only adds the language marker to "first level" code blocks (and not to code blocks in comments inside of code examples).
r? @steveklabnik
The source code snippet uses `"whatever".as_bytes()` but the compilation error message uses `b"whatever"`. Both should be consistent with each other.
r? @steveklabnik
Minor tweak: the text explaining the Borrow trait talks about slices, but the example immediately following just uses a simple reference; there are no slices involved.
r? @steveklabnik
This adds strictly more information to the source files and reduces the
need for customized tooling to render the book.
(While this should not change the output of _rustbook_, it is very
useful when rendering the sources with external tools like Pandoc.)
Tiny fixes collected while reading through the Rust book. If they're too nitpicky please let me know and I'll ignore the next ones. :)
The spaces after the function and closure arguments might be intentional, but they do not make much sense: the usual formatting doesn't have such spaces, and they aren't helping align the three lines together either.
r? @steveklabnik (as suggested by [CONTRIBUTING.md](https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md))
This PR fixes two little typos in the Dining Philosophers example.
Also, there are two style points that may have been oversights but may have been deliberate, so I'll just bring them up here:
1) In the last paragraph, you say
> You’ll notice we can introduce a new binding to `table` here, and it will shadow the old one. This is often used so that you don’t need to come up with two unique names.
You already said something similar to this in the Guessing Game, but maybe you intended for this example to be independent of that one.
2) In "Rust Inside Other Languages," you introduce the idea of the "global interpreter lock" and then refer to it as the GIL a few paragraphs later without explicitly stating that GIL == global interpreter lock. It's reasonable to expect readers to make the connection, but maybe that's not what you intended.
Excellent work on the examples! Congrats on 1.0!
r? @steveklabnik
Fix the link to the "static initialization order fiasco" discussion in the C++ Frequently Questioned Answers.
At present the link points to a mail message summarizing the decision not to have resumable exceptions, but the FAQ means to refer to a discussion of the "static initialization order fiasco". I've made my best guess at what it meant to refer to.
The Traits chapter uses "adding methods to `int`" as an example of "something bad", but there is no such thing as `int` anymore, right? So I changed it to `i32`.
The download links of Windows installers on the Nightly Rust page are using beta builds instead of nightly builds, which caused some confusions when I was setting up my env. Probably it's better to use the links of nightly builds here.
The Traits chapter uses "adding methods to `int`" as an example of "something bad", but there is no such thing as `int` anymore, right? So I changed it to `i32`.
The download links of Windows installers on the Nightly Rust page are using beta builds instead of nightly builds, which caused some confusions when I was setting up my env. Probably it's better to use the links of nightly builds here.
I fixed the typo of the value of e in the memory tables. It is a reference to d, and so it should contain the memory location of d. I also fixed the incorrectly formatted tables so they display properly in html pages.
The enums chapter at the moment is ... weird. The examples aren't about enums, they're about structs, and most of the chapter talks about how enums don't support comparison operators by default (which is also true of other compound data types.) I think there was a story here once, but some coherency got lost in refactoring.
There are two preliminary patches here, one to combine the struct and tuple-struct chapters, and one to document unit-like structs, because enum syntax is easier to explain once you have those three. The final patch moves the enum chapter after the struct chapter, and rewrites most of it to talk about enums usefully (including covering matches on enums).
r? @steveklabnik
I did a read through of the manual. This commit corrects various small points and expands some sections, while avoiding too much detail.
r? @steveklabnik
At the moment, http://doc.rust-lang.org/error-index.html isn't linked to from anywhere (except Reddit). This should allow search engines to find error codes!
I also capitalised "The Standard Library" and neatened a few bits of grammar.
Also fixed: `#[main]` inside one of the error descriptions.
I corrected some pretty obvious textual mistakes. One thing requires more attention - the paragraph at line 133 in Ownership. It was confusing, so I changed it, but I am no sure if this is what the author had in mind.
Hiiii, I've got another chunk of updates to the grammar documentation! ⭐🌟🌠
Chipping away at #22445, still have some more to go. I'm learning so much!!!
Maybe it's me, but I really needed an example to understand if let and refutable statements.
Playpen: http://is.gd/mjX3Gf
Let me know if the variable names are too, uh, culinary.
Several Minor API / Reference Documentation Fixes
- Fix a few small errors in the reference.
- Fix paper cuts in the API docs.
Fixes#24882Fixes#25233Fixes#25250
The reference was claiming all vectors all bounds-checked at run-time, when constant vectors are usually checked at compile-time.
For the changed example see http://is.gd/28ak9E
Also fixed a minor grammar issue.
Corrected "Ownership":
- [`Variable bindings`] link was not processed properly.
- Changed the paragraph about move semantics with two vectors, because it was confusing.
- Removed "So it may not be as inefficient as it initially seems", because there is nothing that seems inefficient in copying pointers only.
- Other text corrections.
Fixed copied-and-pasted text mistakes.
Revised the paragraph about moving a vector (taking into account suggestions by echochamber).
Fixed markdown.
Fixes requested by steveklabnik.
Brought back a sentence about supposed inefficiency.
Between ffc5f1c, when grammar.md was created by copying parts of the
reference, and 8cf2552, when all EBNF was removed from reference.md,
there were parts of the grammar that were updated in reference.md but
not grammar.md, and then they weren't copied over because they existed
already, but they were slightly out of date.
Example: the `path_item : ident | "self" ;` rule in Use declarations was
changed from "mod" to "self" in the reference in 195fd9a but wasn't
updated in the grammar.
The reference was claiming all vectors all bounds-checked at run-time, when constant vectors are usually checked at compile-time.
For the changed example see http://is.gd/28ak9E
I think there's a trivial missing word in the Mutability document. I reformatted the resulting paragraph in vim, which seems to match what the rest of the document is doing as far as word wrapping.
Edit: I found another minor thing as I continued reading.
P.S. I'm re-reading the docs, since so much has changed since my first read, and they've gotten even better! Nice job!
r? @steveklabnik
I've found that there are still huge amounts of occurrences of `task`s in the documentation. This PR tries to eliminate all of them in favor of `thread`.
This syntax was removed in b24a3b8 but references remained in the
grammar, the reference, rustdoc generation, and some auxiliary test
files that don't seem to have been used since 812637e.
An automated script was run against the `.rs` and `.md` files,
subsituting every occurrence of `task` with `thread`. In the `.rs`
files, only the texts in the comment blocks were affected.
If you have 0 references (`&T`) to a resource, presumably, you could
have a mutable reference (`&mut T`). So this only start to make sense
at having 1 reference to a resource.
This also made me realize that I wasn't using the correct term,
'associated functions', rather than 'static methods'. So I corrected
that in the method syntax chapter.
This also made me realize that I wasn't using the correct term,
'associated functions', rather than 'static methods'. So I corrected
that in the method syntax chapter.
- `File::open` is for opening a file in read-only mode
- `File::create` is for opening a file in write-only mode, which is what we want instead for this example to make sense
- I found n error in the book, before contributing the patch to fix it, I had to find where they were hosted
- It took me quite look to find where within the rust-lang *organisation* it was! ... and this should make it easier for the next person in the same position
- `FIle::open` is for opening a file in read-only mode
- `FIle::create` is for opening a file in write-only mode, which is what we want instead for this example to make sense
- I found n error in the book, before contributing the patch to fix it, I had to find where they were hosted
- It took me quite look to find where within the rust-lang *organisation* it was!
Hi! While researching stuff for the reference and the grammar, I came across a few mentions of using the `priv` keyword that was removed in 0.11.0 (#13547, #8122, rust-lang/rfcs#26, [RFC 0026](https://github.com/rust-lang/rfcs/blob/master/text/0026-remove-priv.md)).
One occurrence is a mention in the reference, a few are in comments, and a few are marking test functions. I left the test that makes sure you can't name an ident `priv` since it's still a reserved keyword. I did a little grepping around for `priv `, priv in backticks, `Private` etc and I think the remaining instances are fine, but if anyone knows anywhere in particular I should check for any other lingering mentions of `priv`, please let me know and I would be happy to! 🍂🌊
I'm interested in helping out with #16676 but more in the grammar than the reference-- here's my first chunk, more to come!! 🎉
I did pull a bit *out* of the reference, though, that was more relevant to the grammar but wasn't moved over as part of #24729.
I'm looking at, e.g. https://github.com/rust-lang/rust/blob/master/src/libsyntax/ast.rs, as the source of truth, please let me know if I should be checking against something else instead/in addition.
r? @steveklabnik
Since #24783, the style guidelines recommend that unit tests should live in a submodule `tests` rather than `test` to not clash with the possible use of libtest. This is especially important for benchmark tests as they require libtest. Fixes#24923.
