Some minor docs improvements for TRPL #30755
Conversation
In a straight-through read of "Syntax and Semantics," the first time we meet a generic, and the first time we meet a vector, is when a Vec<T> shows up in this example. I'm not sure that I could argue that the whole section should appear later in the book than the ones on vectors and generics, so instead just give the reader a brief introduction to both and a promise to follow up later.
In a straight-through read of "Syntax and Semantics," the concept of a "reference" is used here before it is explained. Mention that and link to the section explaining references.
|
Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @Manishearth (or someone else) soon. If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. Due to the way GitHub handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes. Please see the contribution instructions for more information. |
| related to the vector, even the heap-allocated memory. This happens | ||
| deterministically, at the end of the scope. | ||
| When `v` comes into scope, a new [vector][] is created, and it allocates space | ||
| on the heap for each of its elements. When `v` goes out of scope at the end of |
There was a problem hiding this comment.
Keep the link to the heap section?
There was a problem hiding this comment.
Oops! That was accidental. Will do.
|
Thanks for the improvements! r? @steveklabnik on the chapter/section stuff |
| @@ -14,7 +14,7 @@ Even then, Rust still allows precise control like a low-level language would. | |||
|
|
|||
| [rust]: https://www.rust-lang.org | |||
|
|
|||
| “The Rust Programming Language” is split into sections. This introduction | |||
| “The Rust Programming Language” is split into chapters. This introduction | |||
There was a problem hiding this comment.
This has always been a confusing-ish pain point: what is a section and what is a chapter? Syntax and Semantics is wayyy to long for a chapter, but the others are too short.
Oh well.
There was a problem hiding this comment.
Considered LaTeX-style Part / Chapter / Section divisions? Not all Parts need to be broken into Chapters, iirc. But maybe this is only intuitive for me because I've authored LaTeX documents before. Probably not worth a bikeshed discussion, so I won't modify this any further within this PR.
|
Hey @datagrok ! Thanks so much for this!
Yeah, I worked really hard to not have forward references originally, but some snuck in. Thanks for noticing. Would you mind editing out the |
|
@bors: r+ rollup |
|
📌 Commit fcc3563 has been approved by |
|
Thanks again! |
I'm working my way through TRPL beginning at "Syntax and Semantics" as was recommended in a previous version. I'm expecting the chapter to incrementally build up my knowledge of the language section by section, assuming no prior Rust experience. So it was a bit of a speed-bump to encounter references and the vector type in a code example long before they had been defined and explained. Another commit in this PR tries to make consistent what is a "chapter" of TRPL versus a "section." Just a nit-pick, but not thinking about that stuff keeps my focus on the important material. My background: Python programmer since ~2000, with moderate exposure to C, C++, assembly, operating systems, and system architecture in university several years ago. For your kind consideration, feel welcome to use or drop or rework any part of this.
I'm working my way through TRPL beginning at "Syntax and Semantics" as was recommended in a previous version.
I'm expecting the chapter to incrementally build up my knowledge of the language section by section, assuming no prior Rust experience. So it was a bit of a speed-bump to encounter references and the vector type in a code example long before they had been defined and explained.
Another commit in this PR tries to make consistent what is a "chapter" of TRPL versus a "section." Just a nit-pick, but not thinking about that stuff keeps my focus on the important material.
My background: Python programmer since ~2000, with moderate exposure to C, C++, assembly, operating systems, and system architecture in university several years ago.
For your kind consideration, feel welcome to use or drop or rework any part of this.