Merge pull request #715 from ehuss/code-block-audit

Audit code blocks.

src/abi.md

@@ -68,7 +68,8 @@ The *`link_section` attribute* specifies the section of the object file that a
 [function] or [static]'s content will be placed into. It uses the
 [_MetaNameValueStr_] syntax to specify the section name.
 
-```rust,ignore
+<!-- no_run: don't link. The format of the section name is platform-specific. -->
+```rust,no_run
 #[no_mangle]
 #[link_section = ".example_section"]
 pub static VAR1: u32 = 1;
@@ -80,7 +81,7 @@ The *`export_name` attribute* specifies the name of the symbol that will be
 exported on a [function] or [static]. It uses the [_MetaNameValueStr_] syntax
 to specify the symbol name.
 
-```rust,ignore
+```rust
 #[export_name = "exported_symbol_name"]
 pub fn name_in_rust() { }
 ```

src/attributes/codegen.md

@@ -49,7 +49,8 @@ enable code generation of that function for specific platform architecture
 features. It uses the [_MetaListNameValueStr_] syntax with a single key of
 `enable` whose value is a string of comma-separated feature names to enable.
 
-```rust,ignore
+```rust
+# #[cfg(target_feature = "avx2")]
 #[target_feature(enable = "avx2")]
 unsafe fn foo_avx2() {}
 ```

src/attributes/type_system.md

@@ -66,7 +66,8 @@ Non-exhaustive types cannot be constructed outside of the defining crate:
   with a [_StructExpression_] \(including with [functional update syntax]).
 - [`enum`][enum] instances can be constructed in an [_EnumerationVariantExpression_].
 
-```rust,ignore (requires multiple crates)
+<!-- ignore: requires external crates -->
+```rust,ignore
 // `Config`, `Error`, and `Message` are types defined in an upstream crate that have been
 // annotated as `#[non_exhaustive]`.
 use upstream::{Config, Error, Message};
@@ -99,7 +100,8 @@ There are limitations when matching on non-exhaustive types outside of the defin
 - When pattern matching on a non-exhaustive [`enum`][enum], matching on a variant does not
   contribute towards the exhaustiveness of the arms.
 
-```rust, ignore (requires multiple crates)
+<!-- ignore: requires external crates -->
+```rust, ignore
 // `Config`, `Error`, and `Message` are types defined in an upstream crate that have been
 // annotated as `#[non_exhaustive]`.
 use upstream::{Config, Error, Message};

src/conditional-compilation.md

@@ -264,6 +264,7 @@ When the configuration predicate is true, this attribute expands out to the
 attributes listed after the predicate. For example, the following module will
 either be found at `linux.rs` or `windows.rs` based on the target.
 
+<!-- ignore: `mod` needs multiple files -->
 ```rust,ignore
 #[cfg_attr(linux, path = "linux.rs")]
 #[cfg_attr(windows, path = "windows.rs")]
@@ -273,6 +274,7 @@ mod os;
 Zero, one, or more attributes may be listed. Multiple attributes will each be
 expanded into separate attributes. For example:
 
+<!-- ignore: fake attributes -->
 ```rust,ignore
 #[cfg_attr(feature = "magic", sparkles, crackles)]
 fn bewitched() {}

src/crates-and-source-files.md

@@ -53,7 +53,7 @@ that apply to the containing module, most of which influence the behavior of
 the compiler. The anonymous crate module can have additional attributes that
 apply to the crate as a whole.
 
-```rust,no_run
+```rust
 // Specify the crate name.
 #![crate_name = "projx"]
 
@@ -75,7 +75,8 @@ essentially to treat the source file as an executable script. The shebang
 can only occur at the beginning of the file (but after the optional
 _UTF8BOM_). It is ignored by the compiler. For example:
 
-```text,ignore
+<!-- ignore: tests don't like shebang -->
+```rust,ignore
 #!/usr/bin/env rustx
 
 fn main() {
@@ -136,7 +137,7 @@ other object being linked to defines `main`.
 The *`crate_name` [attribute]* may be applied at the crate level to specify the
 name of the crate with the [_MetaNameValueStr_] syntax.
 
-```rust,ignore
+```rust
 #![crate_name = "mycrate"]
 ```
 

src/expressions/await-expr.md

@@ -51,6 +51,7 @@ context, there must be some task context available.
 Effectively, an `<expr>.await` expression is roughly
 equivalent to the following (this desugaring is not normative):
 
+<!-- ignore: example expansion -->
 ```rust,ignore
 match /* <expr> */ {
     mut pinned => loop {

src/expressions/field-expr.md

@@ -10,6 +10,7 @@ A _field expression_ consists of an expression followed by a single dot and an
 field of a [struct] or [union]. To call a function stored in a struct,
 parentheses are needed around the field expression.
 
+<!-- ignore: needs lots of support code -->
 ```rust,ignore
 mystruct.myfield;
 foo().x;

src/expressions/if-expr.md

@@ -97,6 +97,7 @@ assert_eq!(a, 3);
 
 An `if let` expression is equivalent to a [`match` expression] as follows:
 
+<!-- ignore: expansion example -->
 ```rust,ignore
 if let PATS = EXPR {
     /* body */
@@ -107,6 +108,7 @@ if let PATS = EXPR {
 
 is equivalent to
 
+<!-- ignore: expansion example -->
 ```rust,ignore
 match EXPR {
     PATS => { /* body */ },
@@ -135,6 +137,7 @@ of the language (the implementation of if-let chains - see [eRFC 2947][_eRFCIfLe
 When lazy boolean operator expression is desired, this can be achieved
 by using parenthesis as below:
 
+<!-- ignore: psuedo code -->
 ```rust,ignore
 // Before...
 if let PAT = EXPR && EXPR { .. }

src/expressions/loop-expr.md

@@ -93,6 +93,7 @@ while let _ = 5 {
 A `while let` loop is equivalent to a `loop` expression containing a [`match`
 expression] as follows.
 
+<!-- ignore: expansion example -->
 ```rust,ignore
 'label: while let PATS = EXPR {
     /* loop body */
@@ -101,6 +102,7 @@ expression] as follows.
 
 is equivalent to
 
+<!-- ignore: expansion example -->
 ```rust,ignore
 'label: loop {
     match EXPR {
@@ -156,6 +158,7 @@ assert_eq!(sum, 55);
 
 A for loop is equivalent to the following block expression.
 
+<!-- ignore: expansion example -->
 ```rust,ignore
 'label: for PATTERN in iter_expr {
     /* loop body */
@@ -164,6 +167,7 @@ A for loop is equivalent to the following block expression.
 
 is equivalent to
 
+<!-- ignore: expansion example -->
 ```rust,ignore
 {
     let result = match IntoIterator::into_iter(iter_expr) {

src/expressions/operator-expr.md

@@ -260,7 +260,9 @@ functions and macros in the standard library can then use that assumption
 above, these operators implicitly take shared borrows of their operands,
 evaluating them in [place expression context][place expression]:
 
-```rust,ignore
+```rust
+# let a = 1;
+# let b = 1;
 a == b;
 // is equivalent to
 ::std::cmp::PartialEq::eq(&a, &b);

src/items/enumerations.md

@@ -91,7 +91,7 @@ using a [primitive representation] or the [`C` representation].
 
 It is an error when two variants share the same discriminant.
 
-```rust,ignore
+```rust,compile_fail
 enum SharedDiscriminantError {
     SharedA = 1,
     SharedB = 1
@@ -107,7 +107,7 @@ enum SharedDiscriminantError2 {
 It is also an error to have an unspecified discriminant where the previous
 discriminant is the maximum value for the size of the discriminant.
 
-```rust,ignore
+```rust,compile_fail
 #[repr(u8)]
 enum OverflowingDiscriminantError {
     Max = 255,

src/items/extern-crates.md

@@ -28,6 +28,7 @@ In this case the `as` clause must be used to specify the name to bind it to.
 
 Three examples of `extern crate` declarations:
 
+<!-- ignore: requires external crates -->
 ```rust,ignore
 extern crate pcre;
 
@@ -43,6 +44,7 @@ details).
 
 Here is an example:
 
+<!-- ignore: requires external crates -->
 ```rust,ignore
 // Importing the Cargo package hello-world
 extern crate hello_world; // hyphen replaced with an underscore

src/items/external-blocks.md

@@ -64,7 +64,7 @@ By default external blocks assume that the library they are calling uses the
 standard C ABI on the specific platform. Other ABIs may be specified using an
 `abi` string, as shown here:
 
-```rust,ignore
+```rust
 // Interface to the Windows API
 extern "stdcall" { }
 ```
@@ -97,7 +97,7 @@ There are also some platform-specific ABI strings:
 Functions within external blocks may be variadic by specifying `...` after one
 or more named arguments in the argument list:
 
-```rust,ignore
+```rust
 extern {
     fn foo(x: i32, ...);
 }
@@ -128,6 +128,7 @@ name for the items within an `extern` block when importing symbols from the
 host environment. The default module name is `env` if `wasm_import_module` is
 not specified.
 
+<!-- ignore: requires extern linking -->
 ```rust,ignore
 #[link(name = "crypto")]
 extern {
@@ -156,7 +157,7 @@ The `link_name` attribute may be specified on declarations inside an `extern`
 block to indicate the symbol to import for the given function or static. It
 uses the [_MetaNameValueStr_] syntax to specify the name of the symbol.
 
-```rust,ignore
+```rust
 extern {
     #[link_name = "actual_symbol_name"]
     fn name_in_rust();
@@ -184,4 +185,4 @@ restrictions as [regular function parameters].
 [_Visibility_]: ../visibility-and-privacy.md
 [_WhereClause_]: generics.md#where-clauses
 [attributes]: ../attributes.md
-[regular function parameters]: functions.md#attributes-on-function-parameters
+[regular function parameters]: functions.md#attributes-on-function-parameters

src/items/functions.md

@@ -58,6 +58,7 @@ the body of the function will short-cut that implicit return, if reached.
 
 For example, the function above behaves as if it was written as:
 
+<!-- ignore: example expansion -->
 ```rust,ignore
 // argument_0 is the actual first argument passed from the caller
 let (value, _) = argument_0;
@@ -115,14 +116,16 @@ sufficient context to determine the type parameters. For example,
 The `extern` function qualifier allows providing function _definitions_ that can
 be called with a particular ABI:
 
++<!-- ignore: fake ABI -->
 ```rust,ignore
-extern "ABI" fn foo() { ... }
+extern "ABI" fn foo() { /* ... */ }
 ```
 
 These are often used in combination with [external block] items which provide
 function _declarations_ that can be used to call functions without providing
 their _definition_:
 
++<!-- ignore: fake ABI -->
 ```rust,ignore
 extern "ABI" {
   fn foo(); /* no body */
@@ -376,6 +379,7 @@ For example, the following code defines an inert `some_inert_attribute` attribut
 is not formally defined anywhere and the `some_proc_macro_attribute` procedural macro is
 responsible for detecting its presence and removing it from the output token stream.
 
+<!-- ignore: requires proc macro -->
 ```rust,ignore
 #[some_proc_macro_attribute]
 fn foo_oof(#[some_inert_attribute] arg: u8) {

src/items/generics.md

@@ -69,7 +69,7 @@ types when defining the item. It is an error to have `Copy` or `Clone`as a
 bound on a mutable reference, [trait object] or [slice][arrays] or `Sized` as a
 bound on a trait object or slice.
 
-```rust,ignore
+```rust,compile_fail
 struct A<T>
 where
     T: Iterator,            // Could use A<T: Iterator> instead
@@ -92,6 +92,7 @@ attributes may give meaning to it.
 This example shows using a custom derive attribute to modify the meaning of a
 generic parameter.
 
+<!-- ignore: requires proc macro derive -->
 ```rust,ignore
 // Assume that the derive for MyFlexibleClone declared `my_flexible_clone` as
 // an attribute it understands.

src/items/modules.md

@@ -74,6 +74,7 @@ For `path` attributes on modules not inside inline module blocks, the file
 path is relative to the directory the source file is located. For example, the
 following code snippet would use the paths shown based on where it is located:
 
+<!-- ignore: requires external files -->
 ```rust,ignore
 #[path = "foo.rs"]
 mod c;
@@ -95,6 +96,7 @@ it is the same except the path starts with a directory with the name of the
 non-mod-rs module. For example, the following code snippet would use the paths
 shown based on where it is located:
 
+<!-- ignore: requires external files -->
 ```rust,ignore
 mod inline {
     #[path = "other.rs"]
@@ -110,6 +112,7 @@ Source File    | `inner`'s File Location   | `inner`'s Module Path
 An example of combining the above rules of `path` attributes on inline modules
 and nested modules within (applies to both mod-rs and non-mod-rs files):
 
+<!-- ignore: requires external files -->
 ```rust,ignore
 #[path = "thread_files"]
 mod thread {

src/items/unions.md

@@ -35,8 +35,11 @@ The expression above creates a value of type `MyUnion` and initializes the
 storage using field `f1`. The union can be accessed using the same syntax as
 struct fields:
 
-```rust,ignore
-let f = u.f1;
+```rust
+# union MyUnion { f1: u32, f2: f32 }
+#
+# let u = MyUnion { f1: 1 };
+let f = unsafe { u.f1 };
 ```
 
 ## Reading and writing union fields
@@ -135,18 +138,19 @@ have to be adjusted to account for this fact. As a result, if one field of a
 union is borrowed, all its remaining fields are borrowed as well for the same
 lifetime.
 
-```rust,ignore
+```rust,compile_fail
+# union MyUnion { f1: u32, f2: f32 }
 // ERROR: cannot borrow `u` (via `u.f2`) as mutable more than once at a time
 fn test() {
     let mut u = MyUnion { f1: 1 };
     unsafe {
         let b1 = &mut u.f1;
-                      ---- first mutable borrow occurs here (via `u.f1`)
+//                    ---- first mutable borrow occurs here (via `u.f1`)
         let b2 = &mut u.f2;
-                      ^^^^ second mutable borrow occurs here (via `u.f2`)
+//                    ^^^^ second mutable borrow occurs here (via `u.f2`)
         *b1 = 5;
     }
-    - first borrow ends here
+//  - first borrow ends here
     assert_eq!(unsafe { u.f1 }, 5);
 }
 ```

src/items/use-declarations.md

@@ -98,7 +98,7 @@ use crate::foo::baz::foobaz;    // good: foo is at the root of the crate
 
 mod foo {
 
-    mod example {
+    pub mod example {
         pub mod iter {}
     }
 
@@ -124,9 +124,14 @@ fn main() {}
 > accessing items in the crate root. Using the example above, the following
 > `use` paths work in 2015 but not 2018:
 >
-> ```rust,ignore
+> ```rust,edition2015
+> # mod foo {
+> #     pub mod example { pub mod iter {} }
+> #     pub mod baz { pub fn foobaz() {} }
+> # }
 > use foo::example::iter;
 > use ::foo::baz::foobaz;
+> # fn main() {}
 > ```
 >
 > The 2015 edition does not allow use declarations to reference the [extern prelude].