From e22ceea1a751f7a66277c323fc39c05832f59214 Mon Sep 17 00:00:00 2001 From: "Michael F. Lamb" Date: Wed, 6 Jan 2016 15:46:58 -0800 Subject: [PATCH 1/5] Explain surprising new syntax appearing in example code 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 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. --- src/doc/book/ownership.md | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/src/doc/book/ownership.md b/src/doc/book/ownership.md index 17b263ef00ab7..0a13d813f7488 100644 --- a/src/doc/book/ownership.md +++ b/src/doc/book/ownership.md @@ -51,15 +51,24 @@ fn foo() { } ``` -When `v` comes into scope, a new [`Vec`][vect] is created. In this case, the -vector also allocates space on [the heap][heap], for the three elements. When -`v` goes out of scope at the end of `foo()`, Rust will clean up everything -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 +`foo()`, Rust will clean up everything related to the vector, even the +heap-allocated memory. This happens deterministically, at the end of the scope. -[vect]: ../std/vec/struct.Vec.html +We'll cover [vectors][vector] in detail later in this chapter; we only use them +here as an example of a type that allocates space on the heap at runtime. They +behave like [arrays][], except their size may change by `push()`ing more +elements onto them. + +Vectors have a [generic type][generics] `Vec`, so in this example `v` will have type +`Vec`. We'll cover generics in detail later in this chapter. + +[arrays]: primitive-types.html#arrays +[vector]: vectors.html [heap]: the-stack-and-the-heap.html [bindings]: variable-bindings.html +[generics]: generics.html # Move semantics From 3557e6941dd99f22fd0ff9d2685d3807e92d17a5 Mon Sep 17 00:00:00 2001 From: "Michael F. Lamb" Date: Wed, 6 Jan 2016 16:02:03 -0800 Subject: [PATCH 2/5] Link to references section when they first appear 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. --- src/doc/book/primitive-types.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/src/doc/book/primitive-types.md b/src/doc/book/primitive-types.md index a8c7a7d41573e..43b7e67e0389b 100644 --- a/src/doc/book/primitive-types.md +++ b/src/doc/book/primitive-types.md @@ -167,8 +167,11 @@ variable binding. Slices have a defined length, can be mutable or immutable. ## Slicing syntax You can use a combo of `&` and `[]` to create a slice from various things. The -`&` indicates that slices are similar to references, and the `[]`s, with a -range, let you define the length of the slice: +`&` indicates that slices are similar to [references][], which we will cover in +detail later in this section. The `[]`s, with a range, let you define the +length of the slice: + +[references]: references-and-borrowing.html ```rust let a = [0, 1, 2, 3, 4]; From 936678adb10b8dee7a9f83d5fc7526c036daddd3 Mon Sep 17 00:00:00 2001 From: "Michael F. Lamb" Date: Wed, 6 Jan 2016 16:04:01 -0800 Subject: [PATCH 3/5] Link to section on references when we use the term prior to defining it --- src/doc/book/primitive-types.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/doc/book/primitive-types.md b/src/doc/book/primitive-types.md index 43b7e67e0389b..ccfa94ad8bbe3 100644 --- a/src/doc/book/primitive-types.md +++ b/src/doc/book/primitive-types.md @@ -192,11 +192,13 @@ documentation][slice]. # `str` Rust’s `str` type is the most primitive string type. As an [unsized type][dst], -it’s not very useful by itself, but becomes useful when placed behind a reference, -like [`&str`][strings]. As such, we’ll just leave it at that. +it’s not very useful by itself, but becomes useful when placed behind a +reference, like `&str`. We'll elaborate further when we cover +[Strings][strings] and [references][]. [dst]: unsized-types.html [strings]: strings.html +[references]: references-and-borrowing.html You can find more documentation for `str` [in the standard library documentation][str]. From 3a6dbb30a21be8d237055479af613e30415b0c56 Mon Sep 17 00:00:00 2001 From: "Michael F. Lamb" Date: Wed, 6 Jan 2016 16:04:47 -0800 Subject: [PATCH 4/5] Be consistent about what is a "chapter" versus a "section" --- src/doc/book/README.md | 2 +- src/doc/book/closures.md | 2 +- src/doc/book/effective-rust.md | 2 +- src/doc/book/error-handling.md | 18 +++++++++--------- src/doc/book/getting-started.md | 4 ++-- src/doc/book/guessing-game.md | 2 +- src/doc/book/learn-rust.md | 2 +- src/doc/book/syntax-and-semantics.md | 2 +- 8 files changed, 17 insertions(+), 17 deletions(-) diff --git a/src/doc/book/README.md b/src/doc/book/README.md index d16746e777a3a..9f9b6a9b043dd 100644 --- a/src/doc/book/README.md +++ b/src/doc/book/README.md @@ -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 is the first. After this: * [Getting started][gs] - Set up your computer for Rust development. diff --git a/src/doc/book/closures.md b/src/doc/book/closures.md index 7d4452a4c8470..24993477ede25 100644 --- a/src/doc/book/closures.md +++ b/src/doc/book/closures.md @@ -208,7 +208,7 @@ different. Rust’s implementation of closures is a bit different than other languages. They are effectively syntax sugar for traits. You’ll want to make sure to have read -the [traits chapter][traits] before this one, as well as the chapter on [trait +the [traits][traits] section before this one, as well as the section on [trait objects][trait-objects]. [traits]: traits.html diff --git a/src/doc/book/effective-rust.md b/src/doc/book/effective-rust.md index 582ed3b7e65c5..65873c80e55e4 100644 --- a/src/doc/book/effective-rust.md +++ b/src/doc/book/effective-rust.md @@ -3,6 +3,6 @@ So you’ve learned how to write some Rust code. But there’s a difference between writing *any* Rust code and writing *good* Rust code. -This section consists of relatively independent tutorials which show you how to +This chapter consists of relatively independent tutorials which show you how to take your Rust to the next level. Common patterns and standard library features will be introduced. Read these sections in any order of your choosing. diff --git a/src/doc/book/error-handling.md b/src/doc/book/error-handling.md index be60ea8f81fc3..f24f7d1dbb173 100644 --- a/src/doc/book/error-handling.md +++ b/src/doc/book/error-handling.md @@ -5,18 +5,18 @@ errors in a particular way. Generally speaking, error handling is divided into two broad categories: exceptions and return values. Rust opts for return values. -In this chapter, we intend to provide a comprehensive treatment of how to deal +In this section, we intend to provide a comprehensive treatment of how to deal with errors in Rust. More than that, we will attempt to introduce error handling one piece at a time so that you'll come away with a solid working knowledge of how everything fits together. When done naïvely, error handling in Rust can be verbose and annoying. This -chapter will explore those stumbling blocks and demonstrate how to use the +section will explore those stumbling blocks and demonstrate how to use the standard library to make error handling concise and ergonomic. # Table of Contents -This chapter is very long, mostly because we start at the very beginning with +This section is very long, mostly because we start at the very beginning with sum types and combinators, and try to motivate the way Rust does error handling incrementally. As such, programmers with experience in other expressive type systems may want to jump around. @@ -636,7 +636,7 @@ Thus far, we've looked at error handling where everything was either an `Option` and a `Result`? Or what if you have a `Result` and a `Result`? Handling *composition of distinct error types* is the next challenge in front of us, and it will be the major theme throughout the rest of -this chapter. +this section. ## Composing `Option` and `Result` @@ -648,7 +648,7 @@ Of course, in real code, things aren't always as clean. Sometimes you have a mix of `Option` and `Result` types. Must we resort to explicit case analysis, or can we continue using combinators? -For now, let's revisit one of the first examples in this chapter: +For now, let's revisit one of the first examples in this section: ```rust,should_panic use std::env; @@ -1319,7 +1319,7 @@ and [`cause`](../std/error/trait.Error.html#method.cause), but the limitation remains: `Box` is opaque. (N.B. This isn't entirely true because Rust does have runtime reflection, which is useful in some scenarios that are [beyond the scope of this -chapter](https://crates.io/crates/error).) +section](https://crates.io/crates/error).) It's time to revisit our custom `CliError` type and tie everything together. @@ -1486,7 +1486,7 @@ and [`fmt::Result`](../std/fmt/type.Result.html). # Case study: A program to read population data -This chapter was long, and depending on your background, it might be +This section was long, and depending on your background, it might be rather dense. While there is plenty of example code to go along with the prose, most of it was specifically designed to be pedagogical. So, we're going to do something new: a case study. @@ -1512,7 +1512,7 @@ and [`rustc-serialize`](https://crates.io/crates/rustc-serialize) crates. We're not going to spend a lot of time on setting up a project with Cargo because it is already covered well in [the Cargo -chapter](../book/hello-cargo.html) and [Cargo's documentation][14]. +section](../book/hello-cargo.html) and [Cargo's documentation][14]. To get started from scratch, run `cargo new --bin city-pop` and make sure your `Cargo.toml` looks something like this: @@ -2108,7 +2108,7 @@ handling. # The Short Story -Since this chapter is long, it is useful to have a quick summary for error +Since this section is long, it is useful to have a quick summary for error handling in Rust. These are some good “rules of thumb." They are emphatically *not* commandments. There are probably good reasons to break every one of these heuristics! diff --git a/src/doc/book/getting-started.md b/src/doc/book/getting-started.md index 17fc5d9233d19..a4c028e85b0d7 100644 --- a/src/doc/book/getting-started.md +++ b/src/doc/book/getting-started.md @@ -1,13 +1,13 @@ % Getting Started -This first section of the book will get us going with Rust and its tooling. +This first chapter of the book will get us going with Rust and its tooling. First, we’ll install Rust. Then, the classic ‘Hello World’ program. Finally, we’ll talk about Cargo, Rust’s build system and package manager. # Installing Rust The first step to using Rust is to install it. Generally speaking, you’ll need -an Internet connection to run the commands in this chapter, as we’ll be +an Internet connection to run the commands in this section, as we’ll be downloading Rust from the internet. We’ll be showing off a number of commands using a terminal, and those lines all diff --git a/src/doc/book/guessing-game.md b/src/doc/book/guessing-game.md index 323bcbc95033c..6665d1f87d818 100644 --- a/src/doc/book/guessing-game.md +++ b/src/doc/book/guessing-game.md @@ -7,7 +7,7 @@ prompt us to enter a guess. Upon entering our guess, it will tell us if we’re too low or too high. Once we guess correctly, it will congratulate us. Sounds good? -Along the way, we’ll learn a little bit about Rust. The next section, ‘Syntax +Along the way, we’ll learn a little bit about Rust. The next chapter, ‘Syntax and Semantics’, will dive deeper into each part. # Set up diff --git a/src/doc/book/learn-rust.md b/src/doc/book/learn-rust.md index 1a02bc95e9d9c..7be7fa4f039a7 100644 --- a/src/doc/book/learn-rust.md +++ b/src/doc/book/learn-rust.md @@ -1,6 +1,6 @@ % Learn Rust -Welcome! This section has a few tutorials that teach you Rust through building +Welcome! This chapter has a few tutorials that teach you Rust through building projects. You’ll get a high-level overview, but we’ll skim over the details. If you’d prefer a more ‘from the ground up’-style experience, check diff --git a/src/doc/book/syntax-and-semantics.md b/src/doc/book/syntax-and-semantics.md index cce985c9e484c..e9ec26dccdcdc 100644 --- a/src/doc/book/syntax-and-semantics.md +++ b/src/doc/book/syntax-and-semantics.md @@ -1,6 +1,6 @@ % Syntax and Semantics -This section breaks Rust down into small chunks, one for each concept. +This chapter breaks Rust down into small chunks, one for each concept. If you’d like to learn Rust from the bottom up, reading this in order is a great way to do that. From fcc356373bba8c20a18d26bc81242c77c4153089 Mon Sep 17 00:00:00 2001 From: "Michael F. Lamb" Date: Thu, 7 Jan 2016 11:44:03 -0800 Subject: [PATCH 5/5] Remove extraneous [], replace accidental removed link to heap section --- src/doc/book/ownership.md | 12 ++++++------ src/doc/book/primitive-types.md | 4 ++-- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/src/doc/book/ownership.md b/src/doc/book/ownership.md index 0a13d813f7488..a62d31d362b14 100644 --- a/src/doc/book/ownership.md +++ b/src/doc/book/ownership.md @@ -51,21 +51,21 @@ fn foo() { } ``` -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 -`foo()`, Rust will clean up everything related to the vector, even the +When `v` comes into scope, a new [vector] is created, and it allocates space on +[the heap][heap] for each of its elements. When `v` goes out of scope at the +end of `foo()`, Rust will clean up everything related to the vector, even the heap-allocated memory. This happens deterministically, at the end of the scope. -We'll cover [vectors][vector] in detail later in this chapter; we only use them +We'll cover [vectors] in detail later in this chapter; we only use them here as an example of a type that allocates space on the heap at runtime. They -behave like [arrays][], except their size may change by `push()`ing more +behave like [arrays], except their size may change by `push()`ing more elements onto them. Vectors have a [generic type][generics] `Vec`, so in this example `v` will have type `Vec`. We'll cover generics in detail later in this chapter. [arrays]: primitive-types.html#arrays -[vector]: vectors.html +[vectors]: vectors.html [heap]: the-stack-and-the-heap.html [bindings]: variable-bindings.html [generics]: generics.html diff --git a/src/doc/book/primitive-types.md b/src/doc/book/primitive-types.md index ccfa94ad8bbe3..d6188fa7cdcf8 100644 --- a/src/doc/book/primitive-types.md +++ b/src/doc/book/primitive-types.md @@ -167,7 +167,7 @@ variable binding. Slices have a defined length, can be mutable or immutable. ## Slicing syntax You can use a combo of `&` and `[]` to create a slice from various things. The -`&` indicates that slices are similar to [references][], which we will cover in +`&` indicates that slices are similar to [references], which we will cover in detail later in this section. The `[]`s, with a range, let you define the length of the slice: @@ -194,7 +194,7 @@ documentation][slice]. Rust’s `str` type is the most primitive string type. As an [unsized type][dst], it’s not very useful by itself, but becomes useful when placed behind a reference, like `&str`. We'll elaborate further when we cover -[Strings][strings] and [references][]. +[Strings][strings] and [references]. [dst]: unsized-types.html [strings]: strings.html