From 2851702ee44cdb77e42d0b906277264246ff61dc Mon Sep 17 00:00:00 2001 From: FuGangqiang Date: Sun, 26 Apr 2015 19:42:39 +0800 Subject: [PATCH 1/5] fix doc --- src/doc/trpl/enums.md | 20 ++++++++++---------- src/doc/trpl/generics.md | 2 +- src/doc/trpl/if-let.md | 2 +- src/doc/trpl/vectors.md | 3 ++- 4 files changed, 14 insertions(+), 13 deletions(-) diff --git a/src/doc/trpl/enums.md b/src/doc/trpl/enums.md index 80ea25eb35ce9..815a5aa36812e 100644 --- a/src/doc/trpl/enums.md +++ b/src/doc/trpl/enums.md @@ -28,6 +28,16 @@ In `Character`, for instance, `Digit` gives a meaningful name for an `i32` value, where `Other` is only a name. However, the fact that they represent distinct categories of `Character` is a very useful property. +We use the `::` syntax to use the name of each variant: They’re scoped by the name +of the `enum` itself. This allows both of these to work: + +```rust,ignore +Character::Digit(10); +Hand::Digit; +``` + +Both variants are named `Digit`, but they’re scoped to the `enum` name. + The variants of an `enum` by default are not comparable with equality operators (`==`, `!=`), have no ordering (`<`, `>=`, etc.), and do not support other binary operations such as `*` and `+`. As such, the following code is invalid @@ -48,16 +58,6 @@ let four_is_smaller = four <= ten; let four_equals_ten = four == ten; ``` -We use the `::` syntax to use the name of each variant: They’re scoped by the name -of the `enum` itself. This allows both of these to work: - -```rust,ignore -Character::Digit(10); -Hand::Digit; -``` - -Both variants are named `Digit`, but since they’re scoped to the `enum` name, - Not supporting these operations may seem rather limiting, but it’s a limitation which we can overcome. There are two ways: by implementing equality ourselves, or by pattern matching variants with [`match`][match] expressions, which you’ll diff --git a/src/doc/trpl/generics.md b/src/doc/trpl/generics.md index 517a6e6064253..6058b0b8ce76c 100644 --- a/src/doc/trpl/generics.md +++ b/src/doc/trpl/generics.md @@ -83,7 +83,7 @@ fn takes_anything(x: T) { ``` The syntax has two parts: the `` says “this function is generic over one -type, `T`”, and the `x: T` says “x has the type `T`.” +type, `T`”, and the `x: T` says “x has the type `T`”. Multiple arguments can have the same generic type: diff --git a/src/doc/trpl/if-let.md b/src/doc/trpl/if-let.md index 7173303e3b152..4872ed6a77347 100644 --- a/src/doc/trpl/if-let.md +++ b/src/doc/trpl/if-let.md @@ -65,7 +65,7 @@ loop as long as a value matches a certain pattern. It turns code like this: loop { match option { Some(x) => println!("{}", x), - _ => break, + _ => break, } } ``` diff --git a/src/doc/trpl/vectors.md b/src/doc/trpl/vectors.md index 28d815c4eb735..446c4d9725c79 100644 --- a/src/doc/trpl/vectors.md +++ b/src/doc/trpl/vectors.md @@ -19,6 +19,8 @@ There’s an alternate form of `vec!` for repeating an initial value: let v = vec![0; 10]; // ten zeroes ``` +[generic]: generics.html + ## Accessing elements To get the value at a particular index in the vector, we use `[]`s: @@ -56,4 +58,3 @@ Vectors have many more useful methods, which you can read about in [their API documentation][vec]. [vec]: ../std/vec/index.html -[generic]: generics.html From 9ba69240e1fa8eec69d1924874b930526bbf6bd3 Mon Sep 17 00:00:00 2001 From: FuGangqiang Date: Mon, 27 Apr 2015 09:26:13 +0800 Subject: [PATCH 2/5] fix doc again --- src/doc/trpl/enums.md | 2 +- src/doc/trpl/generics.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/doc/trpl/enums.md b/src/doc/trpl/enums.md index 815a5aa36812e..d779b5edabc13 100644 --- a/src/doc/trpl/enums.md +++ b/src/doc/trpl/enums.md @@ -1,6 +1,6 @@ % Enums -Rust has a ‘sum type’, an `enum`. Enums are an incredibly useful feature of +Rust has a‘sum type’, an `enum`. Enums are an incredibly useful feature of Rust, and are used throughout the standard library. An `enum` is a type which relates a set of alternates to a specific name. For example, below we define `Character` to be either a `Digit` or something else. diff --git a/src/doc/trpl/generics.md b/src/doc/trpl/generics.md index 6058b0b8ce76c..517a6e6064253 100644 --- a/src/doc/trpl/generics.md +++ b/src/doc/trpl/generics.md @@ -83,7 +83,7 @@ fn takes_anything(x: T) { ``` The syntax has two parts: the `` says “this function is generic over one -type, `T`”, and the `x: T` says “x has the type `T`”. +type, `T`”, and the `x: T` says “x has the type `T`.” Multiple arguments can have the same generic type: From ae5f43f24b50ce5aa48d80ff58ef550be045adae Mon Sep 17 00:00:00 2001 From: FuGangqiang Date: Tue, 28 Apr 2015 20:30:54 +0800 Subject: [PATCH 3/5] fix doc --- src/doc/trpl/casting-between-types.md | 2 +- src/doc/trpl/macros.md | 24 ++++++++++++------------ src/doc/trpl/mutability.md | 4 ++-- src/doc/trpl/raw-pointers.md | 2 +- src/doc/trpl/unsafe.md | 4 ++-- 5 files changed, 18 insertions(+), 18 deletions(-) diff --git a/src/doc/trpl/casting-between-types.md b/src/doc/trpl/casting-between-types.md index f0c673b561a0e..dbacd405065d4 100644 --- a/src/doc/trpl/casting-between-types.md +++ b/src/doc/trpl/casting-between-types.md @@ -43,7 +43,7 @@ what it does is very simple, but very scary. It tells Rust to treat a value of one type as though it were another type. It does this regardless of the typechecking system, and just completely trusts you. -[intrinsic]: intrinsics.html +[intrinsics]: intrinsics.html In our previous example, we know that an array of four `u8`s represents a `u32` properly, and so we want to do the cast. Using `transmute` instead of `as`, diff --git a/src/doc/trpl/macros.md b/src/doc/trpl/macros.md index 9d01f104ddaaf..9814ae2654c8b 100644 --- a/src/doc/trpl/macros.md +++ b/src/doc/trpl/macros.md @@ -12,7 +12,7 @@ or cumbersome to express that pattern as a generic function, a trait, or anything else within Rust’s semantics. Macros allow us to abstract at a syntactic level. A macro invocation is -shorthand for an "expanded" syntactic form. This expansion happens early in +shorthand for an‘expanded’syntactic form. This expansion happens early in compilation, before any static checking. As a result, macros can capture many patterns of code reuse that Rust’s core abstractions cannot. @@ -23,7 +23,7 @@ difficult to design a well-behaved macro! Additionally, compiler errors in macro code are harder to interpret, because they describe problems in the expanded code, not the source-level form that developers use. -These drawbacks make macros something of a "feature of last resort". That’s not +These drawbacks make macros something of a‘feature of last resort’. That’s not to say that macros are bad; they are part of Rust because sometimes they’re needed for truly concise, well-abstracted code. Just keep this tradeoff in mind. @@ -98,7 +98,7 @@ cases. Above, we had This is like a `match` expression arm, but the matching happens on Rust syntax trees, at compile time. The semicolon is optional on the last (here, only) -case. The "pattern" on the left-hand side of `=>` is known as a ‘matcher’. +case. The‘pattern’on the left-hand side of `=>` is known as a ‘matcher’. These have [their own little grammar] within the language. [their own little grammar]: ../reference.html#macros @@ -154,7 +154,7 @@ $( ``` Each matched expression `$x` will produce a single `push` statement in the -macro expansion. The repetition in the expansion proceeds in "lockstep" with +macro expansion. The repetition in the expansion proceeds in‘lockstep’with repetition in the matcher (more on this in a moment). Because `$x` was already declared as matching an expression, we don’t repeat @@ -190,7 +190,7 @@ shorthand for a data type could be valid as either an expression or a pattern. The repetition operator follows two principal rules: -1. `$(...)*` walks through one "layer" of repetitions, for all of the `$name`s +1. `$(...)*` walks through one‘layer’of repetitions, for all of the `$name`s it contains, in lockstep, and 2. each `$name` must be under at least as many `$(...)*`s as it was matched against. If it is under more, it’ll be duplicated, as appropriate. @@ -219,12 +219,12 @@ fn main() { ``` That’s most of the matcher syntax. These examples use `$(...)*`, which is a -"zero or more" match. Alternatively you can write `$(...)+` for a "one or -more" match. Both forms optionally include a separator, which can be any token +‘zero or more’match. Alternatively you can write `$(...)+` for a‘one or +more’match. Both forms optionally include a separator, which can be any token except `+` or `*`. This system is based on -"[Macro-by-Example](http://www.cs.indiana.edu/ftp/techreports/TR206.pdf)" +‘[Macro-by-Example](http://www.cs.indiana.edu/ftp/techreports/TR206.pdf)’ (PDF link). # Hygiene @@ -316,7 +316,7 @@ fn main() { This works because Rust has a [hygienic macro system][]. Each macro expansion happens in a distinct ‘syntax context’, and each variable is tagged with the syntax context where it was introduced. It’s as though the variable `state` -inside `main` is painted a different "color" from the variable `state` inside +inside `main` is painted a different‘color’from the variable `state` inside the macro, and therefore they don’t conflict. [hygienic macro system]: http://en.wikipedia.org/wiki/Hygienic_macro @@ -418,7 +418,7 @@ tell you about the syntax contexts. they are unstable and require feature gates. * `log_syntax!(...)` will print its arguments to standard output, at compile - time, and "expand" to nothing. + time, and‘expand’to nothing. * `trace_macros!(true)` will enable a compiler message every time a macro is expanded. Use `trace_macros!(false)` later in expansion to turn it off. @@ -471,7 +471,7 @@ which syntactic form it matches. * `block`: a brace-delimited sequence of statements. Example: `{ log(error, "hi"); return 12; }`. * `item`: an [item][]. Examples: `fn foo() { }`; `struct Bar;`. -* `meta`: a "meta item", as found in attributes. Example: `cfg(target_os = "windows")`. +* `meta`: a‘meta item’, as found in attributes. Example: `cfg(target_os = "windows")`. * `tt`: a single token tree. There are additional rules regarding the next token after a metavariable: @@ -765,7 +765,7 @@ as `unimplemented!` until you’re ready to write them. # Procedural macros If Rust’s macro system can’t do what you need, you may want to write a -[compiler plugin](plugins.html) instead. Compared to `macro_rules!` +[compiler plugin](compiler-plugins.html) instead. Compared to `macro_rules!` macros, this is significantly more work, the interfaces are much less stable, and bugs can be much harder to track down. In exchange you get the flexibility of running arbitrary Rust code within the compiler. Syntax diff --git a/src/doc/trpl/mutability.md b/src/doc/trpl/mutability.md index 816bfb1797061..4e9e87e0b75b3 100644 --- a/src/doc/trpl/mutability.md +++ b/src/doc/trpl/mutability.md @@ -84,7 +84,7 @@ safety, and the mechanism by which Rust guarantees it, the > You may have one or the other of these two kinds of borrows, but not both at > the same time: -> +> > * 0 to N references (`&T`) to a resource. > * exactly one mutable reference (`&mut T`) @@ -169,7 +169,7 @@ struct Point { y: Cell, } -let mut point = Point { x: 5, y: Cell::new(6) }; +let point = Point { x: 5, y: Cell::new(6) }; point.y.set(7); diff --git a/src/doc/trpl/raw-pointers.md b/src/doc/trpl/raw-pointers.md index ab6ff18501ed5..4a37af3c22782 100644 --- a/src/doc/trpl/raw-pointers.md +++ b/src/doc/trpl/raw-pointers.md @@ -80,7 +80,7 @@ Raw pointers are useful for FFI: Rust’s `*const T` and `*mut T` are similar to C’s `const T*` and `T*`, respectfully. For more about this use, consult the [FFI chapter][ffi]. -[ffi]: ffi.md +[ffi]: ffi.html # References and raw pointers diff --git a/src/doc/trpl/unsafe.md b/src/doc/trpl/unsafe.md index 7fe9a1fd27e8e..a79aa3304071e 100644 --- a/src/doc/trpl/unsafe.md +++ b/src/doc/trpl/unsafe.md @@ -12,7 +12,7 @@ two contexts. The first one is to mark a function as unsafe: ```rust unsafe fn danger_will_robinson() { - // scary stuff + // scary stuff } ``` @@ -101,7 +101,7 @@ Rust has a feature called ‘`static mut`’ which allows for mutable global sta Doing so can cause a data race, and as such is inherently not safe. For more details, see the [static][static] section of the book. -[static]: static.html +[static]: const-and-static.html#static ## Dereference a raw pointer From 2eb61d438f36faf328f172ae6db3cdbf6ce827fe Mon Sep 17 00:00:00 2001 From: FuGangqiang Date: Thu, 30 Apr 2015 00:50:26 +0800 Subject: [PATCH 4/5] fix doc link --- src/doc/complement-lang-faq.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/doc/complement-lang-faq.md b/src/doc/complement-lang-faq.md index fa4e0304d1a0f..8ff3bea7e53da 100644 --- a/src/doc/complement-lang-faq.md +++ b/src/doc/complement-lang-faq.md @@ -20,8 +20,8 @@ Some examples that demonstrate different aspects of the language: * The standard library's [json] module. Enums and pattern matching [sprocketnes]: https://github.com/pcwalton/sprocketnes -[hash]: https://github.com/rust-lang/rust/blob/master/src/libstd/hash/mod.rs -[HashMap]: https://github.com/rust-lang/rust/blob/master/src/libcollections/hashmap.rs +[hash]: https://github.com/rust-lang/rust/blob/master/src/libcore/hash/mod.rs +[HashMap]: https://github.com/rust-lang/rust/blob/master/src/libstd/collections/hash/map.rs#L309 [json]: https://github.com/rust-lang/rust/blob/master/src/libserialize/json.rs You may also be interested in browsing [trending Rust repositories][github-rust] on GitHub. From 4550f38e916779d32da38f6ae67cf7e104243e30 Mon Sep 17 00:00:00 2001 From: FuGangqiang Date: Thu, 30 Apr 2015 20:23:41 +0800 Subject: [PATCH 5/5] fix doc:turn whitespaces back --- src/doc/trpl/enums.md | 2 +- src/doc/trpl/macros.md | 20 ++++++++++---------- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/src/doc/trpl/enums.md b/src/doc/trpl/enums.md index d779b5edabc13..815a5aa36812e 100644 --- a/src/doc/trpl/enums.md +++ b/src/doc/trpl/enums.md @@ -1,6 +1,6 @@ % Enums -Rust has a‘sum type’, an `enum`. Enums are an incredibly useful feature of +Rust has a ‘sum type’, an `enum`. Enums are an incredibly useful feature of Rust, and are used throughout the standard library. An `enum` is a type which relates a set of alternates to a specific name. For example, below we define `Character` to be either a `Digit` or something else. diff --git a/src/doc/trpl/macros.md b/src/doc/trpl/macros.md index 9814ae2654c8b..b9e6076ad73e1 100644 --- a/src/doc/trpl/macros.md +++ b/src/doc/trpl/macros.md @@ -12,7 +12,7 @@ or cumbersome to express that pattern as a generic function, a trait, or anything else within Rust’s semantics. Macros allow us to abstract at a syntactic level. A macro invocation is -shorthand for an‘expanded’syntactic form. This expansion happens early in +shorthand for an ‘expanded’ syntactic form. This expansion happens early in compilation, before any static checking. As a result, macros can capture many patterns of code reuse that Rust’s core abstractions cannot. @@ -23,7 +23,7 @@ difficult to design a well-behaved macro! Additionally, compiler errors in macro code are harder to interpret, because they describe problems in the expanded code, not the source-level form that developers use. -These drawbacks make macros something of a‘feature of last resort’. That’s not +These drawbacks make macros something of a ‘feature of last resort’. That’s not to say that macros are bad; they are part of Rust because sometimes they’re needed for truly concise, well-abstracted code. Just keep this tradeoff in mind. @@ -98,7 +98,7 @@ cases. Above, we had This is like a `match` expression arm, but the matching happens on Rust syntax trees, at compile time. The semicolon is optional on the last (here, only) -case. The‘pattern’on the left-hand side of `=>` is known as a ‘matcher’. +case. The ‘pattern’ on the left-hand side of `=>` is known as a ‘matcher’. These have [their own little grammar] within the language. [their own little grammar]: ../reference.html#macros @@ -154,7 +154,7 @@ $( ``` Each matched expression `$x` will produce a single `push` statement in the -macro expansion. The repetition in the expansion proceeds in‘lockstep’with +macro expansion. The repetition in the expansion proceeds in ‘lockstep’ with repetition in the matcher (more on this in a moment). Because `$x` was already declared as matching an expression, we don’t repeat @@ -190,7 +190,7 @@ shorthand for a data type could be valid as either an expression or a pattern. The repetition operator follows two principal rules: -1. `$(...)*` walks through one‘layer’of repetitions, for all of the `$name`s +1. `$(...)*` walks through one ‘layer’ of repetitions, for all of the `$name`s it contains, in lockstep, and 2. each `$name` must be under at least as many `$(...)*`s as it was matched against. If it is under more, it’ll be duplicated, as appropriate. @@ -219,8 +219,8 @@ fn main() { ``` That’s most of the matcher syntax. These examples use `$(...)*`, which is a -‘zero or more’match. Alternatively you can write `$(...)+` for a‘one or -more’match. Both forms optionally include a separator, which can be any token +‘zero or more’ match. Alternatively you can write `$(...)+` for a ‘one or +more’ match. Both forms optionally include a separator, which can be any token except `+` or `*`. This system is based on @@ -316,7 +316,7 @@ fn main() { This works because Rust has a [hygienic macro system][]. Each macro expansion happens in a distinct ‘syntax context’, and each variable is tagged with the syntax context where it was introduced. It’s as though the variable `state` -inside `main` is painted a different‘color’from the variable `state` inside +inside `main` is painted a different ‘color’ from the variable `state` inside the macro, and therefore they don’t conflict. [hygienic macro system]: http://en.wikipedia.org/wiki/Hygienic_macro @@ -418,7 +418,7 @@ tell you about the syntax contexts. they are unstable and require feature gates. * `log_syntax!(...)` will print its arguments to standard output, at compile - time, and‘expand’to nothing. + time, and ‘expand’ to nothing. * `trace_macros!(true)` will enable a compiler message every time a macro is expanded. Use `trace_macros!(false)` later in expansion to turn it off. @@ -471,7 +471,7 @@ which syntactic form it matches. * `block`: a brace-delimited sequence of statements. Example: `{ log(error, "hi"); return 12; }`. * `item`: an [item][]. Examples: `fn foo() { }`; `struct Bar;`. -* `meta`: a‘meta item’, as found in attributes. Example: `cfg(target_os = "windows")`. +* `meta`: a ‘meta item’, as found in attributes. Example: `cfg(target_os = "windows")`. * `tt`: a single token tree. There are additional rules regarding the next token after a metavariable: