Merge pull request #1 from rust-lang-nursery/master

Pulling changes from rust-lang-nursery

Author: samWson

.travis.yml

@@ -9,6 +9,7 @@ install:
 - bash ci/install.sh
 script:
 - mdbook build
+- mdbook test
 notifications:
   email:
     on_success: never

README.md

@@ -30,8 +30,8 @@ To help prevent accidentally introducing broken links, we use the
 invoke this link checker, otherwise it will emit a warning saying it couldn't
 be found.
 
-```
-$ cargo install mdbook-linkcheck
+```bash
+> cargo install mdbook-linkcheck
 ```
 You will need `mdbook` version `>= 0.1`. `linkcheck` will be run automatically
 when you run `mdbook build`.

src/appendix-background.md

@@ -21,7 +21,7 @@ all the remainder. Only at the end of the block is there the
 possibility of branching to more than one place (in MIR, we call that
 final statement the **terminator**):
 
-```
+```mir
 bb0: {
     statement0;
     statement1;
@@ -34,7 +34,7 @@ bb0: {
 Many expressions that you are used to in Rust compile down to multiple
 basic blocks. For example, consider an if statement:
 
-```rust
+```rust,ignore
 a = 1;
 if some_variable {
     b = 1;
@@ -46,7 +46,7 @@ d = 1;
 
 This would compile into four basic blocks:
 
-```
+```mir
 BB0: {
     a = 1;
     if some_variable { goto BB1 } else { goto BB2 }

src/appendix-code-index.md

@@ -6,17 +6,17 @@ compiler.
 
 Item            |  Kind    | Short description           | Chapter            | Declaration
 ----------------|----------|-----------------------------|--------------------|-------------------
-`CodeMap` | struct | The CodeMap maps the AST nodes to their source code | [The parser] | [src/libsyntax/codemap.rs](https://github.com/rust-lang/rust/blob/master/src/libsyntax/codemap.rs)
-`CompileState` | struct | State that is passed to a callback at each compiler pass | [The Rustc Driver] | [src/librustc_driver/driver.rs](https://github.com/rust-lang/rust/blob/master/src/librustc_driver/driver.rs)
+`CodeMap` | struct | The CodeMap maps the AST nodes to their source code | [The parser] | [src/libsyntax/codemap.rs](https://doc.rust-lang.org/nightly/nightly-rustc/syntax/codemap/struct.CodeMap.html)
+`CompileState` | struct | State that is passed to a callback at each compiler pass | [The Rustc Driver] | [src/librustc_driver/driver.rs](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_driver/driver/struct.CompileState.html)
 `DocContext` | struct | A state container used by rustdoc when crawling through a crate to gather its documentation | [Rustdoc] | [src/librustdoc/core.rs](https://github.com/rust-lang/rust/blob/master/src/librustdoc/core.rs)
-`ast::Crate` | struct | Syntax-level representation of a parsed crate | [The parser] | [src/librustc/hir/mod.rs](https://github.com/rust-lang/rust/blob/master/src/libsyntax/ast.rs)
-`hir::Crate` | struct | More abstract, compiler-friendly form of a crate's AST | [The Hir] | [src/librustc/hir/mod.rs](https://github.com/rust-lang/rust/blob/master/src/librustc/hir/mod.rs)
-`ParseSess` | struct | This struct contains information about a parsing session | [the Parser] | [src/libsyntax/parse/mod.rs](https://github.com/rust-lang/rust/blob/master/src/libsyntax/parse/mod.rs)
-`Session` | struct | The data associated with a compilation session | [the Parser], [The Rustc Driver] | [src/librustc/session/mod.html](https://github.com/rust-lang/rust/blob/master/src/librustc/session/mod.rs)
-`StringReader` | struct | This is the lexer used during parsing. It consumes characters from the raw source code being compiled and produces a series of tokens for use by the rest of the parser | [The parser] |  [src/libsyntax/parse/lexer/mod.rs](https://github.com/rust-lang/rust/blob/master/src/libsyntax/parse/lexer/mod.rs)
-`TraitDef` | struct | This struct contains a trait's definition with type information | [The `ty` modules] |  [src/librustc/ty/trait_def.rs](https://github.com/rust-lang/rust/blob/master/src/librustc/ty/trait_def.rs)
-`Ty<'tcx>` | struct | This is the internal representation of a type used for type checking | [Type checking] | [src/librustc/ty/mod.rs](https://github.com/rust-lang/rust/blob/master/src/librustc/ty/mod.rs)
-`TyCtxt<'cx, 'tcx, 'tcx>` | type | The "typing context". This is the central data structure in the compiler. It is the context that you use to perform all manner of queries. | [The `ty` modules] | [src/librustc/ty/context.rs](https://github.com/rust-lang/rust/blob/master/src/librustc/ty/context.rs)
+`ast::Crate` | struct | Syntax-level representation of a parsed crate | [The parser] | [src/librustc/hir/mod.rs](https://doc.rust-lang.org/nightly/nightly-rustc/syntax/ast/struct.Crate.html)
+`hir::Crate` | struct | More abstract, compiler-friendly form of a crate's AST | [The Hir] | [src/librustc/hir/mod.rs](https://doc.rust-lang.org/nightly/nightly-rustc/rustc/hir/struct.Crate.html)
+`ParseSess` | struct | This struct contains information about a parsing session | [the Parser] | [src/libsyntax/parse/mod.rs](https://doc.rust-lang.org/nightly/nightly-rustc/syntax/parse/struct.ParseSess.html)
+`Session` | struct | The data associated with a compilation session | [the Parser], [The Rustc Driver] | [src/librustc/session/mod.html](https://doc.rust-lang.org/nightly/nightly-rustc/rustc/session/struct.Session.html)
+`StringReader` | struct | This is the lexer used during parsing. It consumes characters from the raw source code being compiled and produces a series of tokens for use by the rest of the parser | [The parser] |  [src/libsyntax/parse/lexer/mod.rs](https://doc.rust-lang.org/nightly/nightly-rustc/syntax/parse/lexer/struct.StringReader.html)
+`TraitDef` | struct | This struct contains a trait's definition with type information | [The `ty` modules] |  [src/librustc/ty/trait_def.rs](https://doc.rust-lang.org/nightly/nightly-rustc/rustc/ty/trait_def/struct.TraitDef.html)
+`Ty<'tcx>` | struct | This is the internal representation of a type used for type checking | [Type checking] | [src/librustc/ty/mod.rs](https://doc.rust-lang.org/nightly/nightly-rustc/rustc/ty/type.Ty.html)
+`TyCtxt<'cx, 'tcx, 'tcx>` | type | The "typing context". This is the central data structure in the compiler. It is the context that you use to perform all manner of queries. | [The `ty` modules] | [src/librustc/ty/context.rs](https://doc.rust-lang.org/nightly/nightly-rustc/rustc/ty/struct.TyCtxt.html)
 
 [The HIR]: hir.html
 [The parser]: the-parser.html

src/appendix-stupid-stats.md

@@ -3,7 +3,7 @@
 > **Note:** This is a copy of `@nrc`'s amazing [stupid-stats]. You should find
 > a copy of the code on the GitHub repository although due to the compiler's
 > constantly evolving nature, there is no guarantee it'll compile on the first
-> go. 
+> go.
 
 Many tools benefit from being a drop-in replacement for a compiler. By this, I
 mean that any user of the tool can use `mytool` in all the ways they would
@@ -87,14 +87,16 @@ in [librustc_back](https://github.com/rust-lang/rust/tree/master/src/librustc_ba
 (which also contains some things used primarily during translation).
 
 All these phases are coordinated by the driver. To see the exact sequence, look
-at the `compile_input` function in [librustc_driver/driver.rs](https://github.com/rust-lang/rust/tree/master/src/librustc_driver/driver.rs).
-The driver (which is found in [librust_driver](https://github.com/rust-lang/rust/tree/master/src/librustc_driver))
-handles all the highest level coordination of compilation - handling command
-line arguments, maintaining compilation state (primarily in the `Session`), and
-calling the appropriate code to run each phase of compilation. It also handles
-high level coordination of pretty printing and testing. To create a drop-in
-compiler replacement or a compiler replacement, we leave most of compilation
-alone and customise the driver using its APIs.
+at [the `compile_input` function in `librustc_driver`][compile-input].
+The driver handles all the highest level coordination of compilation - 
+    1. handling command-line arguments 
+    2. maintaining compilation state (primarily in the `Session`)
+    3. calling the appropriate code to run each phase of compilation
+    4. handles high level coordination of pretty printing and testing.
+To create a drop-in compiler replacement or a compiler replacement, 
+we leave most of compilation alone and customise the driver using its APIs.
+
+[compile-input]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_driver/driver/fn.compile_input.html
 
 
 ## The driver customisation APIs
@@ -111,7 +113,7 @@ between phases.
 `CompilerCalls` is a trait that you implement in your tool. It contains a fairly
 ad-hoc set of methods to hook in to the process of processing command line
 arguments and driving the compiler. For details, see the comments in
-[librustc_driver/lib.rs](https://github.com/rust-lang/rust/tree/master/src/librustc_driver/lib.rs).
+[librustc_driver/lib.rs](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_driver/index.html).
 I'll summarise the methods here.
 
 `early_callback` and `late_callback` let you call arbitrary code at different
@@ -175,7 +177,7 @@ foo.rs` (assuming you have a Rust program called `foo.rs`. You can also pass any
 command line arguments that you would normally pass to rustc). When you run it
 you'll see output similar to
 
-```
+```text
 In crate: foo,
 
 Found 12 uses of `println!`;
@@ -203,7 +205,7 @@ should dump stupid-stats' stdout to Cargo's stdout).
 
 Let's start with the `main` function for our tool, it is pretty simple:
 
-```
+```rust,ignore
 fn main() {
     let args: Vec<_> = std::env::args().collect();
     rustc_driver::run_compiler(&args, &mut StupidCalls::new());
@@ -221,7 +223,7 @@ this tool different from rustc.
 
 `StupidCalls` is a mostly empty struct:
 
-```
+```rust,ignore
 struct StupidCalls {
     default_calls: RustcDefaultCalls,
 }
@@ -236,7 +238,7 @@ to keep Cargo happy.
 
 Most of the rest of the impl of `CompilerCalls` is trivial:
 
-```
+```rust,ignore
 impl<'a> CompilerCalls<'a> for StupidCalls {
     fn early_callback(&mut self,
                         _: &getopts::Matches,
@@ -298,7 +300,7 @@ tool does it's actual work by walking the AST. We do that by creating an AST
 visitor and making it walk the AST from the top (the crate root). Once we've
 walked the crate, we print the stats we've collected:
 
-```
+```rust,ignore
 fn build_controller(&mut self, _: &Session) -> driver::CompileController<'a> {
     // We mostly want to do what rustc does, which is what basic() will return.
     let mut control = driver::CompileController::basic();
@@ -338,7 +340,7 @@ That is all it takes to create your own drop-in compiler replacement or custom
 compiler! For the sake of completeness I'll go over the rest of the stupid-stats
 tool.
 
-```
+```rust
 struct StupidVisitor {
     println_count: usize,
     arg_counts: Vec<usize>,
@@ -353,7 +355,7 @@ methods, these walk the AST taking no action. We override `visit_item` and
 functions, modules, traits, structs, and so forth, we're only interested in
 functions) and macros:
 
-```
+```rust,ignore
 impl<'v> visit::Visitor<'v> for StupidVisitor {
     fn visit_item(&mut self, i: &'v ast::Item) {
         match i.node {

src/compiletest.md

@@ -61,7 +61,8 @@ which takes a single argument (which, in this case is a value of 1).
 (rather than the current Rust default of 101 at the time of this writing).  The
 header command and the argument list (if present) are typically separated by a
 colon:
-```
+
+```rust,ignore
 // Copyright 2018 The Rust Project Developers. See the COPYRIGHT
 // file at the top-level directory of this distribution and at
 // http://rust-lang.org/COPYRIGHT.

src/const-eval.md

@@ -35,4 +35,4 @@ integer or fat pointer, it will directly yield the value (via `Value::ByVal` or
 memory allocation (via `Value::ByRef`). This means that the `const_eval`
 function cannot be used to create miri-pointers to the evaluated constant or
 static. If you need that, you need to directly work with the functions in
-[src/librustc_mir/interpret/const_eval.rs](https://github.com/rust-lang/rust/blob/master/src/librustc_mir/interpret/const_eval.rs).
+[src/librustc_mir/interpret/const_eval.rs](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir/interpret/const_eval/).

src/conventions.md

@@ -21,7 +21,7 @@ tidy script runs automatically when you do `./x.py test`.
 
 All files must begin with the following copyright notice:
 
-```
+```rust
 // Copyright 2012-2013 The Rust Project Developers. See the COPYRIGHT
 // file at the top-level directory of this distribution and at
 // http://rust-lang.org/COPYRIGHT.
@@ -48,7 +48,7 @@ tests -- it can be necessary to exempt yourself from this limit. In
 that case, you can add a comment towards the top of the file (after
 the copyright notice) like so:
 
-```
+```rust
 // ignore-tidy-linelength
 ```
 
@@ -61,7 +61,7 @@ Prefer 4-space indent.
 # Coding for correctness
 
 Beyond formatting, there are a few other tips that are worth
-following. 
+following.
 
 ## Prefer exhaustive matches
 

src/high-level-overview.md

@@ -19,7 +19,7 @@ compilation improves, that may change.)
 
 The dependency structure of these crates is roughly a diamond:
 
-```
+```text
                   rustc_driver
                 /      |       \
               /        |         \

src/hir.md

@@ -12,8 +12,8 @@ This chapter covers the main concepts of the HIR.
 You can view the HIR representation of your code by passing the
 `-Zunpretty=hir-tree` flag to rustc:
 
-```
-cargo rustc -- -Zunpretty=hir-tree
+```bash
+> cargo rustc -- -Zunpretty=hir-tree
 ```
 
 ### Out-of-band storage and the `Crate` type

src/how-to-build-and-run.md

@@ -70,8 +70,8 @@ Once you've created a config.toml, you are now ready to run
 `x.py`. There are a lot of options here, but let's start with what is
 probably the best "go to" command for building a local rust:
 
-```
-./x.py build -i --stage 1 src/libstd
+```bash
+> ./x.py build -i --stage 1 src/libstd
 ```
 
 What this command will do is the following:
@@ -106,7 +106,7 @@ will execute the stage2 compiler (which we did not build, but which
 you will likely need to build at some point; for example, if you want
 to run the entire test suite).
 
-```
+```bash
 > rustup toolchain link stage1 build/<host-triple>/stage1
 > rustup toolchain link stage2 build/<host-triple>/stage2
 ```
@@ -115,7 +115,7 @@ Now you can run the rustc you built with. If you run with `-vV`, you
 should see a version number ending in `-dev`, indicating a build from
 your local environment:
 
-```
+```bash
 > rustc +stage1 -vV
 rustc 1.25.0-dev
 binary: rustc

src/incrcomp-debugging.md

@@ -10,7 +10,7 @@ As an example, see `src/test/compile-fail/dep-graph-caller-callee.rs`.
 
 The idea is that you can annotate a test like:
 
-```rust
+```rust,ignore
 #[rustc_if_this_changed]
 fn foo() { }
 
@@ -48,7 +48,7 @@ the graph. You can filter in three ways:
 To filter, use the `RUST_DEP_GRAPH_FILTER` environment variable, which should
 look like one of the following:
 
-```
+```text
 source_filter     // nodes originating from source_filter
 -> target_filter  // nodes that can reach target_filter
 source_filter -> target_filter // nodes in between source_filter and target_filter
@@ -58,14 +58,14 @@ source_filter -> target_filter // nodes in between source_filter and target_filt
 A node is considered to match a filter if all of those strings appear in its
 label. So, for example:
 
-```
+```text
 RUST_DEP_GRAPH_FILTER='-> TypeckTables'
 ```
 
 would select the predecessors of all `TypeckTables` nodes. Usually though you
 want the `TypeckTables` node for some particular fn, so you might write:
 
-```
+```text
 RUST_DEP_GRAPH_FILTER='-> TypeckTables & bar'
 ```
 
@@ -75,7 +75,7 @@ with `bar` in their name.
 Perhaps you are finding that when you change `foo` you need to re-type-check
 `bar`, but you don't think you should have to. In that case, you might do:
 
-```
+```text
 RUST_DEP_GRAPH_FILTER='Hir & foo -> TypeckTables & bar'
 ```
 
@@ -105,8 +105,10 @@ check of `bar` and you don't think there should be. You dump the
 dep-graph as described in the previous section and open `dep-graph.txt`
 to see something like:
 
-    Hir(foo) -> Collect(bar)
-    Collect(bar) -> TypeckTables(bar)
+```text
+Hir(foo) -> Collect(bar)
+Collect(bar) -> TypeckTables(bar)
+```
 
 That first edge looks suspicious to you. So you set
 `RUST_FORBID_DEP_GRAPH_EDGE` to `Hir&foo -> Collect&bar`, re-run, and

src/macro-expansion.md

@@ -15,7 +15,7 @@ expansion works.
 It's helpful to have an example to refer to. For the remainder of this chapter,
 whenever we refer to the "example _definition_", we mean the following:
 
-```rust
+```rust,ignore
 macro_rules! printer {
     (print $mvar:ident) => {
         println!("{}", $mvar);
@@ -45,7 +45,7 @@ worrying about _where_. For more information about tokens, see the
 
 Whenever we refer to the "example _invocation_", we mean the following snippet:
 
-```rust
+```rust,ignore
 printer!(print foo); // Assume `foo` is a variable defined somewhere else...
 ```
 
@@ -65,7 +65,7 @@ defined in [`src/libsyntax/ext/tt/macro_parser.rs`][code_mp].
 
 The interface of the macro parser is as follows (this is slightly simplified):
 
-```rust
+```rust,ignore
 fn parse(
     sess: ParserSession,
     tts: TokenStream,
@@ -156,7 +156,7 @@ TODO
 
 
 [code_dir]: https://github.com/rust-lang/rust/tree/master/src/libsyntax/ext/tt
-[code_mp]: https://github.com/rust-lang/rust/tree/master/src/libsyntax/ext/tt/macro_parser.rs
-[code_mr]: https://github.com/rust-lang/rust/tree/master/src/libsyntax/ext/tt/macro_rules.rs
-[code_parse_int]: https://github.com/rust-lang/rust/blob/a97cd17f5d71fb4ec362f4fbd79373a6e7ed7b82/src/libsyntax/ext/tt/macro_parser.rs#L421
+[code_mp]: https://doc.rust-lang.org/nightly/nightly-rustc/syntax/ext/tt/macro_parser/
+[code_mr]: https://doc.rust-lang.org/nightly/nightly-rustc/syntax/ext/tt/macro_rules/
+[code_parse_int]: https://doc.rust-lang.org/nightly/nightly-rustc/syntax/ext/tt/macro_parser/fn.parse.html
 [parsing]: ./the-parser.html