From 73bd0ba91efe68b3d2932d7a2abbdde7308d0738 Mon Sep 17 00:00:00 2001 From: Ted Mielczarek Date: Wed, 30 Sep 2015 12:33:38 -0400 Subject: [PATCH 1/9] Fix module links in std::fmt and the Rust book's documentation chapter. The links in the rustdoc for several places in fmt were trying to link to the std::fmt module but actually linking to std, which was confusing. While trying to figure out why I noticed that the documentation chapter of the Rust book has examples that show this same bug (although it doesn't seem widespread in practice). --- src/doc/trpl/documentation.md | 4 ++-- src/libcore/fmt/mod.rs | 18 +++++++++--------- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/src/doc/trpl/documentation.md b/src/doc/trpl/documentation.md index 0a471beb439..5afb9b7f868 100644 --- a/src/doc/trpl/documentation.md +++ b/src/doc/trpl/documentation.md @@ -45,7 +45,7 @@ Rust keeps track of these comments, and uses them when generating documentation. This is important when documenting things like enums: ```rust -/// The `Option` type. See [the module level documentation](../) for more. +/// The `Option` type. See [the module level documentation](index.html) for more. enum Option { /// No value None, @@ -57,7 +57,7 @@ enum Option { The above works, but this does not: ```rust,ignore -/// The `Option` type. See [the module level documentation](../) for more. +/// The `Option` type. See [the module level documentation](index.html) for more. enum Option { None, /// No value Some(T), /// Some value `T` diff --git a/src/libcore/fmt/mod.rs b/src/libcore/fmt/mod.rs index 8c596eb3e99..65206f42b39 100644 --- a/src/libcore/fmt/mod.rs +++ b/src/libcore/fmt/mod.rs @@ -298,7 +298,7 @@ impl<'a> Display for Arguments<'a> { /// /// For more information on formatters, see [the module-level documentation][module]. /// -/// [module]: ../index.html +/// [module]: index.html /// /// # Examples /// @@ -393,7 +393,7 @@ pub trait Debug { /// /// For more information on formatters, see [the module-level documentation][module]. /// -/// [module]: ../index.html +/// [module]: index.html /// /// # Examples /// @@ -435,7 +435,7 @@ pub trait Display { /// /// For more information on formatters, see [the module-level documentation][module]. /// -/// [module]: ../index.html +/// [module]: index.html /// /// # Examples /// @@ -482,7 +482,7 @@ pub trait Octal { /// /// For more information on formatters, see [the module-level documentation][module]. /// -/// [module]: ../index.html +/// [module]: index.html /// /// # Examples /// @@ -530,7 +530,7 @@ pub trait Binary { /// /// For more information on formatters, see [the module-level documentation][module]. /// -/// [module]: ../index.html +/// [module]: index.html /// /// # Examples /// @@ -578,7 +578,7 @@ pub trait LowerHex { /// /// For more information on formatters, see [the module-level documentation][module]. /// -/// [module]: ../index.html +/// [module]: index.html /// /// # Examples /// @@ -624,7 +624,7 @@ pub trait UpperHex { /// /// For more information on formatters, see [the module-level documentation][module]. /// -/// [module]: ../index.html +/// [module]: index.html /// /// # Examples /// @@ -668,7 +668,7 @@ pub trait Pointer { /// /// For more information on formatters, see [the module-level documentation][module]. /// -/// [module]: ../index.html +/// [module]: index.html /// /// # Examples /// @@ -711,7 +711,7 @@ pub trait LowerExp { /// /// For more information on formatters, see [the module-level documentation][module]. /// -/// [module]: ../index.html +/// [module]: index.html /// /// # Examples /// From 9c70d5160bbd76ed428499d8a54b7a47361b2007 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Wed, 30 Sep 2015 12:39:37 -0400 Subject: [PATCH 2/9] Improve wording in error handling guide The original blog post referred to examples by their file names, and now that it's in guide form, there is no file name. So edit the text so that it makes a bit more sense. Fixes #28428 --- src/doc/trpl/error-handling.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/doc/trpl/error-handling.md b/src/doc/trpl/error-handling.md index a54ba91da2e..7fb1a79dcf1 100644 --- a/src/doc/trpl/error-handling.md +++ b/src/doc/trpl/error-handling.md @@ -182,7 +182,7 @@ analysis is the only way to get at the value stored inside an `Option`. This means that you, as the programmer, must handle the case when an `Option` is `None` instead of `Some(t)`. -But wait, what about `unwrap` used in [`unwrap-double`](#code-unwrap-double)? +But wait, what about `unwrap`,which we used [`previously`](#code-unwrap-double)? There was no case analysis there! Instead, the case analysis was put inside the `unwrap` method for you. You could define it yourself if you want: @@ -211,7 +211,7 @@ that makes `unwrap` ergonomic to use. Unfortunately, that `panic!` means that ### Composing `Option` values -In [`option-ex-string-find`](#code-option-ex-string-find) +In an [example from before](#code-option-ex-string-find), we saw how to use `find` to discover the extension in a file name. Of course, not all file names have a `.` in them, so it's possible that the file name has no extension. This *possibility of absence* is encoded into the types using From d310ad95479369c75bfcd4f126f0b6accc1aaee6 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Wed, 30 Sep 2015 12:42:47 -0400 Subject: [PATCH 3/9] Format panic docs for split_at Fixes #28384 --- src/libcollections/slice.rs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/libcollections/slice.rs b/src/libcollections/slice.rs index 76bdd6dbea1..dabfd168c89 100644 --- a/src/libcollections/slice.rs +++ b/src/libcollections/slice.rs @@ -455,6 +455,8 @@ impl [T] { /// the index `mid` itself) and the second will contain all /// indices from `[mid, len)` (excluding the index `len` itself). /// + /// # Panics + /// /// Panics if `mid > len`. /// /// # Examples From bc0440a63146085fc42a7defbf6f944900f0be3d Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Wed, 30 Sep 2015 13:21:02 -0400 Subject: [PATCH 4/9] Call out slicing syntax more explicitly Fixes #28359 --- src/doc/trpl/primitive-types.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/src/doc/trpl/primitive-types.md b/src/doc/trpl/primitive-types.md index 027909dd058..a8c7a7d4157 100644 --- a/src/doc/trpl/primitive-types.md +++ b/src/doc/trpl/primitive-types.md @@ -162,13 +162,18 @@ A ‘slice’ is a reference to (or “view” into) another data structure. The useful for allowing safe, efficient access to a portion of an array without copying. For example, you might want to reference just one line of a file read into memory. By nature, a slice is not created directly, but from an existing -variable. Slices have a length, can be mutable or not, and in many ways behave -like arrays: +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: ```rust let a = [0, 1, 2, 3, 4]; -let middle = &a[1..4]; // A slice of a: just the elements 1, 2, and 3 let complete = &a[..]; // A slice containing all of the elements in a +let middle = &a[1..4]; // A slice of a: just the elements 1, 2, and 3 ``` Slices have type `&[T]`. We’ll talk about that `T` when we cover From 49fa11c5a5fef15b49abf0a22b0991f1b6ed114b Mon Sep 17 00:00:00 2001 From: Ted Mielczarek Date: Wed, 30 Sep 2015 13:24:39 -0400 Subject: [PATCH 5/9] Fix module links from core::fmt::* to go to std::fmt --- src/libcore/fmt/mod.rs | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/src/libcore/fmt/mod.rs b/src/libcore/fmt/mod.rs index 65206f42b39..69fa0fa1609 100644 --- a/src/libcore/fmt/mod.rs +++ b/src/libcore/fmt/mod.rs @@ -298,7 +298,7 @@ impl<'a> Display for Arguments<'a> { /// /// For more information on formatters, see [the module-level documentation][module]. /// -/// [module]: index.html +/// [module]: ../../std/fmt/index.html /// /// # Examples /// @@ -393,7 +393,7 @@ pub trait Debug { /// /// For more information on formatters, see [the module-level documentation][module]. /// -/// [module]: index.html +/// [module]: ../../std/fmt/index.html /// /// # Examples /// @@ -435,7 +435,7 @@ pub trait Display { /// /// For more information on formatters, see [the module-level documentation][module]. /// -/// [module]: index.html +/// [module]: ../../std/fmt/index.html /// /// # Examples /// @@ -482,7 +482,7 @@ pub trait Octal { /// /// For more information on formatters, see [the module-level documentation][module]. /// -/// [module]: index.html +/// [module]: ../../std/fmt/index.html /// /// # Examples /// @@ -530,7 +530,7 @@ pub trait Binary { /// /// For more information on formatters, see [the module-level documentation][module]. /// -/// [module]: index.html +/// [module]: ../../std/fmt/index.html /// /// # Examples /// @@ -578,7 +578,7 @@ pub trait LowerHex { /// /// For more information on formatters, see [the module-level documentation][module]. /// -/// [module]: index.html +/// [module]: ../../std/fmt/index.html /// /// # Examples /// @@ -624,7 +624,7 @@ pub trait UpperHex { /// /// For more information on formatters, see [the module-level documentation][module]. /// -/// [module]: index.html +/// [module]: ../../std/fmt/index.html /// /// # Examples /// @@ -668,7 +668,7 @@ pub trait Pointer { /// /// For more information on formatters, see [the module-level documentation][module]. /// -/// [module]: index.html +/// [module]: ../../std/fmt/index.html /// /// # Examples /// @@ -711,7 +711,7 @@ pub trait LowerExp { /// /// For more information on formatters, see [the module-level documentation][module]. /// -/// [module]: index.html +/// [module]: ../../std/fmt/index.html /// /// # Examples /// From 201384c1077493e84aaeb3a2370d041678e5aa6d Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Wed, 30 Sep 2015 13:30:43 -0400 Subject: [PATCH 6/9] Cross-reference doc chapter from testing chapter We don't completely cover documentation tests in the testing chapter, since we cover them in the documentation chapter. So make sure people know that. Fixes #28082 --- src/doc/trpl/testing.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/doc/trpl/testing.md b/src/doc/trpl/testing.md index 587f60343c3..452dc13c696 100644 --- a/src/doc/trpl/testing.md +++ b/src/doc/trpl/testing.md @@ -502,3 +502,5 @@ documentation tests: the `_0` is generated for the module test, and `add_two_0` for the function test. These will auto increment with names like `add_two_1` as you add more examples. +We haven’t covered all of the details with writing documentation tests. For more, +please see the [Documentation chapter](documentation.html) From 367f46d7931db1871c7eb5f6bece64c1f2467b18 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Wed, 30 Sep 2015 13:35:33 -0400 Subject: [PATCH 7/9] Make note of performance implications of Read Fixes #28073 --- src/libstd/io/mod.rs | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/src/libstd/io/mod.rs b/src/libstd/io/mod.rs index 54869807cac..a76755dadd3 100644 --- a/src/libstd/io/mod.rs +++ b/src/libstd/io/mod.rs @@ -370,6 +370,13 @@ fn read_to_end(r: &mut R, buf: &mut Vec) -> Result /// throughout `std::io` take and provide types which implement the `Read` /// trait. /// +/// Please note that each call to `read` may involve a system call, and +/// therefore, using something that implements [`BufRead`][bufread], such as +/// [`BufReader`][bufreader], will be more efficient. +/// +/// [bufread]: trait.BufRead.html +/// [bufreader]: struct.BufReader.html +/// /// # Examples /// /// [`File`][file]s implement `Read`: From 9812eb0ef4f1dedd6f25a2c63f755b683b6ce787 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Wed, 30 Sep 2015 13:39:59 -0400 Subject: [PATCH 8/9] Elaborate on the io prelude in the book Fixes #27917 --- src/doc/trpl/guessing-game.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/doc/trpl/guessing-game.md b/src/doc/trpl/guessing-game.md index 94280aa4a33..db484a28cb0 100644 --- a/src/doc/trpl/guessing-game.md +++ b/src/doc/trpl/guessing-game.md @@ -99,9 +99,12 @@ use std::io; We’ll need to take user input, and then print the result as output. As such, we need the `io` library from the standard library. Rust only imports a few things by default into every program, [the ‘prelude’][prelude]. If it’s not in the -prelude, you’ll have to `use` it directly. +prelude, you’ll have to `use` it directly. There is also a second ‘prelude’, the +[`io` prelude][ioprelude], which serves a similar function: you import it, and it +imports a number of useful, `io`-related things. [prelude]: ../std/prelude/index.html +[ioprelude]: ../std/io/prelude/index.html ```rust,ignore fn main() { From 3ef9c1d5f9872c1de797bf4e594f4d54a04ef650 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Wed, 30 Sep 2015 13:46:58 -0400 Subject: [PATCH 9/9] Mention that you can only index with usize Fixes #28693 --- src/doc/trpl/vectors.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/src/doc/trpl/vectors.md b/src/doc/trpl/vectors.md index d8b894a2f65..7b826f08ae6 100644 --- a/src/doc/trpl/vectors.md +++ b/src/doc/trpl/vectors.md @@ -32,6 +32,35 @@ println!("The third element of v is {}", v[2]); The indices count from `0`, so the third element is `v[2]`. +It’s also important to note that you must index with the `usize` type: + +```ignore +let v = vec![1, 2, 3, 4, 5]; + +let i: usize = 0; +let j: i32 = 0; + +// works +v[i]; + +// doesn’t +v[j]; +``` + +Indexing with a non-`usize` type gives an error that looks like this: + +```text +error: the trait `core::ops::Index` is not implemented for the type +`collections::vec::Vec<_>` [E0277] +v[j]; +^~~~ +note: the type `collections::vec::Vec<_>` cannot be indexed by `i32` +error: aborting due to previous error +``` + +There’s a lot of punctuation in that message, but the core of it makes sense: +you cannot index with an `i32`. + ## Iterating Once you have a vector, you can iterate through its elements with `for`. There