From 4a35a732b7ecf50f71218d89b740fc010e86f3ea Mon Sep 17 00:00:00 2001 From: Ori Avtalion Date: Tue, 1 Dec 2015 10:59:31 +0200 Subject: [PATCH 1/6] Fix wording in Guessing Game --- src/doc/book/guessing-game.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/doc/book/guessing-game.md b/src/doc/book/guessing-game.md index 6a513fb2c596..ef829c655589 100644 --- a/src/doc/book/guessing-game.md +++ b/src/doc/book/guessing-game.md @@ -521,11 +521,11 @@ Please input your guess. You guessed: 5 ``` -Great! Next up: let’s compare our guess to the secret guess. +Great! Next up: comparing our guess to the secret number. # Comparing guesses -Now that we’ve got user input, let’s compare our guess to the random guess. +Now that we’ve got user input, let’s compare our guess to the secret number. Here’s our next step, though it doesn’t quite compile yet: ```rust,ignore From dfa0cbcb3e44c440c842d8990d6be85911964aba Mon Sep 17 00:00:00 2001 From: "Paul A. Jungwirth" Date: Tue, 1 Dec 2015 10:03:46 -0800 Subject: [PATCH 2/6] Clarify ambiguity about how to ask Cargo for a specific version --- src/doc/book/guessing-game.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/src/doc/book/guessing-game.md b/src/doc/book/guessing-game.md index 6a513fb2c596..026e58cda31a 100644 --- a/src/doc/book/guessing-game.md +++ b/src/doc/book/guessing-game.md @@ -357,9 +357,13 @@ Cargo uses the dependencies section to know what dependencies on external crates you have, and what versions you require. In this case, we’ve specified version `0.3.0`, which Cargo understands to be any release that’s compatible with this specific version. Cargo understands [Semantic Versioning][semver], which is a standard for writing version -numbers. If we wanted to use only `0.3.0` exactly, we could use `=0.3.0`. If we -wanted to use the latest version we could use `*`; We could use a range of -versions. [Cargo’s documentation][cargodoc] contains more details. +numbers. A bare number like above is actually shorthand for `^0.3.0`, +meaning "anything compatible with 0.3.0". +If we wanted to use only `0.3.0` exactly, we could say `rand="=0.3.0"` +(note the two equal signs). +And if we wanted to use the latest version we could use `*`. +We could also use a range of versions. +[Cargo’s documentation][cargodoc] contains more details. [semver]: http://semver.org [cargodoc]: http://doc.crates.io/crates-io.html From e48030d7d11f2bf90692907ff5f066f25f9eeb5d Mon Sep 17 00:00:00 2001 From: Florian Hahn Date: Tue, 1 Dec 2015 12:54:43 +0100 Subject: [PATCH 3/6] Replace uses of int/uint with isize/uzsize in doc examples --- src/librustc/middle/infer/region_inference/mod.rs | 4 ++-- src/librustc/middle/liveness.rs | 2 +- src/librustc_borrowck/borrowck/check_loans.rs | 4 ++-- src/librustc_borrowck/borrowck/gather_loans/mod.rs | 4 +++- src/librustc_trans/trans/debuginfo/doc.rs | 2 +- src/librustc_trans/trans/meth.rs | 4 ++-- src/librustc_typeck/check/regionck.rs | 8 ++++---- src/librustc_typeck/variance.rs | 14 +++++++------- 8 files changed, 22 insertions(+), 20 deletions(-) diff --git a/src/librustc/middle/infer/region_inference/mod.rs b/src/librustc/middle/infer/region_inference/mod.rs index dd95fc4cc0d8..df620d4a04e7 100644 --- a/src/librustc/middle/infer/region_inference/mod.rs +++ b/src/librustc/middle/infer/region_inference/mod.rs @@ -159,8 +159,8 @@ pub enum RegionResolutionError<'tcx> { /// like to indicate so to the user. /// For example, the following function /// ``` -/// struct Foo { bar: int } -/// fn foo2<'a, 'b>(x: &'a Foo) -> &'b int { +/// struct Foo { bar: isize } +/// fn foo2<'a, 'b>(x: &'a Foo) -> &'b isize { /// &x.bar /// } /// ``` diff --git a/src/librustc/middle/liveness.rs b/src/librustc/middle/liveness.rs index 9b18b79d2615..14c2e1f5aacb 100644 --- a/src/librustc/middle/liveness.rs +++ b/src/librustc/middle/liveness.rs @@ -1583,7 +1583,7 @@ impl<'a, 'tcx> Liveness<'a, 'tcx> { let r = self.should_warn(var); if let Some(name) = r { - // annoying: for parameters in funcs like `fn(x: int) + // annoying: for parameters in funcs like `fn(x: isize) // {ret}`, there is only one node, so asking about // assigned_on_exit() is not meaningful. let is_assigned = if ln == self.s.exit_ln { diff --git a/src/librustc_borrowck/borrowck/check_loans.rs b/src/librustc_borrowck/borrowck/check_loans.rs index f6bb51a26adc..b460c0ec4d0c 100644 --- a/src/librustc_borrowck/borrowck/check_loans.rs +++ b/src/librustc_borrowck/borrowck/check_loans.rs @@ -718,8 +718,8 @@ impl<'a, 'tcx> CheckLoanCtxt<'a, 'tcx> { /// /// For example: /// - /// ``` - /// let a: int; + /// ```ignore + /// let a: isize; /// a = 10; // ok, even though a is uninitialized /// /// struct Point { x: usize, y: usize } diff --git a/src/librustc_borrowck/borrowck/gather_loans/mod.rs b/src/librustc_borrowck/borrowck/gather_loans/mod.rs index 083cc972ccad..f3addf381e0d 100644 --- a/src/librustc_borrowck/borrowck/gather_loans/mod.rs +++ b/src/librustc_borrowck/borrowck/gather_loans/mod.rs @@ -486,7 +486,9 @@ impl<'a, 'tcx> GatherLoanCtxt<'a, 'tcx> { //! come about when variables of `&mut` type are re-borrowed, //! as in this example: //! - //! fn counter<'a>(v: &'a mut Foo) -> &'a mut uint { + //! struct Foo { counter: usize } + //! + //! fn counter<'a>(v: &'a mut Foo) -> &'a mut usize { //! &mut v.counter //! } //! diff --git a/src/librustc_trans/trans/debuginfo/doc.rs b/src/librustc_trans/trans/debuginfo/doc.rs index a91619b2f845..c7d9e3de5a19 100644 --- a/src/librustc_trans/trans/debuginfo/doc.rs +++ b/src/librustc_trans/trans/debuginfo/doc.rs @@ -66,7 +66,7 @@ //! //! ``` //! struct List { -//! value: int, +//! value: isize, //! tail: Option>, //! } //! ``` diff --git a/src/librustc_trans/trans/meth.rs b/src/librustc_trans/trans/meth.rs index 8449d63015ef..795a56b2dcf4 100644 --- a/src/librustc_trans/trans/meth.rs +++ b/src/librustc_trans/trans/meth.rs @@ -456,7 +456,7 @@ fn trans_trait_callee_from_llval<'blk, 'tcx>(bcx: Block<'blk, 'tcx>, /// Generate a shim function that allows an object type like `SomeTrait` to /// implement the type `SomeTrait`. Imagine a trait definition: /// -/// trait SomeTrait { fn get(&self) -> int; ... } +/// trait SomeTrait { fn get(&self) -> isize; ... } /// /// And a generic bit of code: /// @@ -468,7 +468,7 @@ fn trans_trait_callee_from_llval<'blk, 'tcx>(bcx: Block<'blk, 'tcx>, /// What is the value of `x` when `foo` is invoked with `T=SomeTrait`? /// The answer is that it is a shim function generated by this routine: /// -/// fn shim(t: &SomeTrait) -> int { +/// fn shim(t: &SomeTrait) -> isize { /// // ... call t.get() virtually ... /// } /// diff --git a/src/librustc_typeck/check/regionck.rs b/src/librustc_typeck/check/regionck.rs index 549824d22a4a..4f897d91b078 100644 --- a/src/librustc_typeck/check/regionck.rs +++ b/src/librustc_typeck/check/regionck.rs @@ -59,7 +59,7 @@ //! There are a number of troublesome scenarios in the tests //! `region-dependent-*.rs`, but here is one example: //! -//! struct Foo { i: int } +//! struct Foo { i: isize } //! struct Bar { foo: Foo } //! fn get_i(x: &'a Bar) -> &'a int { //! let foo = &x.foo; // Lifetime L1 @@ -233,8 +233,8 @@ impl<'a, 'tcx> Rcx<'a, 'tcx> { /// Consider this silly example: /// /// ``` - /// fn borrow(x: &int) -> &int {x} - /// fn foo(x: @int) -> int { // block: B + /// fn borrow(x: &int) -> &isize {x} + /// fn foo(x: @int) -> isize { // block: B /// let b = borrow(x); // region: /// *b /// } @@ -243,7 +243,7 @@ impl<'a, 'tcx> Rcx<'a, 'tcx> { /// Here, the region of `b` will be ``. `` is constrained to be some subregion of the /// block B and some superregion of the call. If we forced it now, we'd choose the smaller /// region (the call). But that would make the *b illegal. Since we don't resolve, the type - /// of b will be `&.int` and then `*b` will require that `` be bigger than the let and + /// of b will be `&.isize` and then `*b` will require that `` be bigger than the let and /// the `*b` expression, so we will effectively resolve `` to be the block B. pub fn resolve_type(&self, unresolved_ty: Ty<'tcx>) -> Ty<'tcx> { self.fcx.infcx().resolve_type_vars_if_possible(&unresolved_ty) diff --git a/src/librustc_typeck/variance.rs b/src/librustc_typeck/variance.rs index c9035bdff719..910f3b713cf8 100644 --- a/src/librustc_typeck/variance.rs +++ b/src/librustc_typeck/variance.rs @@ -172,14 +172,14 @@ //! //! Now imagine that I have an implementation of `ConvertTo` for `Object`: //! -//! impl ConvertTo for Object { ... } +//! impl ConvertTo for Object { ... } //! //! And I want to call `convertAll` on an array of strings. Suppose //! further that for whatever reason I specifically supply the value of //! `String` for the type parameter `T`: //! //! let mut vector = vec!["string", ...]; -//! convertAll::(vector); +//! convertAll::(vector); //! //! Is this legal? To put another way, can we apply the `impl` for //! `Object` to the type `String`? The answer is yes, but to see why @@ -190,7 +190,7 @@ //! - It will then call the impl of `convertTo()` that is intended //! for use with objects. This has the type: //! -//! fn(self: &Object) -> int +//! fn(self: &Object) -> isize //! //! It is ok to provide a value for `self` of type `&String` because //! `&String <: &Object`. @@ -198,17 +198,17 @@ //! OK, so intuitively we want this to be legal, so let's bring this back //! to variance and see whether we are computing the correct result. We //! must first figure out how to phrase the question "is an impl for -//! `Object,int` usable where an impl for `String,int` is expected?" +//! `Object,isize` usable where an impl for `String,isize` is expected?" //! //! Maybe it's helpful to think of a dictionary-passing implementation of //! type classes. In that case, `convertAll()` takes an implicit parameter //! representing the impl. In short, we *have* an impl of type: //! -//! V_O = ConvertTo for Object +//! V_O = ConvertTo for Object //! //! and the function prototype expects an impl of type: //! -//! V_S = ConvertTo for String +//! V_S = ConvertTo for String //! //! As with any argument, this is legal if the type of the value given //! (`V_O`) is a subtype of the type expected (`V_S`). So is `V_O <: V_S`? @@ -217,7 +217,7 @@ //! covariant, it means that: //! //! V_O <: V_S iff -//! int <: int +//! isize <: isize //! String <: Object //! //! These conditions are satisfied and so we are happy. From 4fb296e07738ddce144a6f9c1097b46fca0eabc4 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Tue, 1 Dec 2015 16:53:48 -0500 Subject: [PATCH 4/6] Small fix to EXE_SUFFIX and DLL_EXTENSION docs --- src/libstd/env.rs | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/src/libstd/env.rs b/src/libstd/env.rs index a63c90c4a91d..760733872ea1 100644 --- a/src/libstd/env.rs +++ b/src/libstd/env.rs @@ -671,9 +671,9 @@ pub mod consts { /// /// Some possible values: /// - /// - .so - /// - .dylib - /// - .dll + /// - so + /// - dylib + /// - dll #[stable(feature = "env", since = "1.0.0")] pub const DLL_EXTENSION: &'static str = super::os::DLL_EXTENSION; @@ -682,7 +682,9 @@ pub mod consts { /// /// Some possible values: /// - /// - exe + /// - .exe + /// - .nexe + /// - .pexe /// - `""` (an empty string) #[stable(feature = "env", since = "1.0.0")] pub const EXE_SUFFIX: &'static str = super::os::EXE_SUFFIX; From ca07c2ec21c4880ed25bc0f22b5af3e601c7b2f2 Mon Sep 17 00:00:00 2001 From: Alex Burka Date: Tue, 1 Dec 2015 18:18:19 -0500 Subject: [PATCH 5/6] trpl: explain how to inhibit rustdoc's auto-main I think this fixes #30137. I basically just repeated some details that were scattered around other places in this document, and emphasized that you probably don't want an `extern crate` or `mod` statement to end up inside a function. --- src/doc/book/documentation.md | 23 +++++++++++++++-------- 1 file changed, 15 insertions(+), 8 deletions(-) diff --git a/src/doc/book/documentation.md b/src/doc/book/documentation.md index 80aed0d1ca7d..0d0fd8cf1d0a 100644 --- a/src/doc/book/documentation.md +++ b/src/doc/book/documentation.md @@ -213,8 +213,8 @@ Let's discuss our sample example documentation: ``` You'll notice that you don't need a `fn main()` or anything here. `rustdoc` will -automatically add a `main()` wrapper around your code, and in the right place. -For example: +automatically add a `main()` wrapper around your code, using heuristics to attempt +to put it in the right place. For example: ```rust /// ``` @@ -242,11 +242,18 @@ Here's the full algorithm rustdoc uses to preprocess examples: `unused_attributes`, and `dead_code`. Small examples often trigger these lints. 3. If the example does not contain `extern crate`, then `extern crate - ;` is inserted. -2. Finally, if the example does not contain `fn main`, the remainder of the - text is wrapped in `fn main() { your_code }` + ;` is inserted (note the lack of `#[macro_use]`). +4. Finally, if the example does not contain `fn main`, the remainder of the + text is wrapped in `fn main() { your_code }`. -Sometimes, this isn't enough, though. For example, all of these code samples +This generated `fn main` can be a problem! If you have `extern crate` or a `mod` +statements in the example code that are referred to by `use` statements, they will +fail to resolve unless you include at least `fn main() {}` to inhibit step 4. +`#[macro_use] extern crate` also does not work except at the crate root, so when +testing macros an explicit `main` is always required. It doesn't have to clutter +up your docs, though -- keep reading! + +Sometimes this algorithm isn't enough, though. For example, all of these code samples with `///` we've been talking about? The raw text: ```text @@ -370,8 +377,8 @@ macro_rules! panic_unless { You’ll note three things: we need to add our own `extern crate` line, so that we can add the `#[macro_use]` attribute. Second, we’ll need to add our own -`main()` as well. Finally, a judicious use of `#` to comment out those two -things, so they don’t show up in the output. +`main()` as well (for reasons discussed above). Finally, a judicious use of +`#` to comment out those two things, so they don’t show up in the output. Another case where the use of `#` is handy is when you want to ignore error handling. Lets say you want the following, From fa0009136dbadb193b1470e09bcee16adaac5797 Mon Sep 17 00:00:00 2001 From: Ori Avtalion Date: Wed, 2 Dec 2015 01:34:08 +0200 Subject: [PATCH 6/6] book: Change mention of unused `return` to `panic!` --- src/doc/book/guessing-game.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/book/guessing-game.md b/src/doc/book/guessing-game.md index 6a513fb2c596..267daf1c488f 100644 --- a/src/doc/book/guessing-game.md +++ b/src/doc/book/guessing-game.md @@ -775,7 +775,7 @@ fn main() { ``` And try it out. But wait, didn’t we just add an infinite loop? Yup. Remember -our discussion about `parse()`? If we give a non-number answer, we’ll `return` +our discussion about `parse()`? If we give a non-number answer, we’ll `panic!` and quit. Observe: ```bash