Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Audit code blocks. #715

Merged
merged 1 commit into from
Nov 8, 2019
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions src/abi.md
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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() { }
```
Expand Down
3 changes: 2 additions & 1 deletion src/attributes/codegen.md
Original file line number Diff line number Diff line change
Expand Up @@ -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() {}
```
Expand Down
6 changes: 4 additions & 2 deletions src/attributes/type_system.md
Original file line number Diff line number Diff line change
Expand Up @@ -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};
Expand Down Expand Up @@ -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};
Expand Down
2 changes: 2 additions & 0 deletions src/conditional-compilation.md
Original file line number Diff line number Diff line change
Expand Up @@ -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")]
Expand All @@ -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() {}
Expand Down
7 changes: 4 additions & 3 deletions src/crates-and-source-files.md
Original file line number Diff line number Diff line change
Expand Up @@ -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"]

Expand All @@ -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() {
Expand Down Expand Up @@ -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"]
```

Expand Down
1 change: 1 addition & 0 deletions src/expressions/await-expr.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down
1 change: 1 addition & 0 deletions src/expressions/field-expr.md
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
3 changes: 3 additions & 0 deletions src/expressions/if-expr.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 */
Expand All @@ -107,6 +108,7 @@ if let PATS = EXPR {

is equivalent to

<!-- ignore: expansion example -->
```rust,ignore
match EXPR {
PATS => { /* body */ },
Expand Down Expand Up @@ -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 { .. }
Expand Down
4 changes: 4 additions & 0 deletions src/expressions/loop-expr.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 */
Expand All @@ -101,6 +102,7 @@ expression] as follows.

is equivalent to

<!-- ignore: expansion example -->
```rust,ignore
'label: loop {
match EXPR {
Expand Down Expand Up @@ -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 */
Expand All @@ -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) {
Expand Down
4 changes: 3 additions & 1 deletion src/expressions/operator-expr.md
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down
4 changes: 2 additions & 2 deletions src/items/enumerations.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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,
Expand Down
2 changes: 2 additions & 0 deletions src/items/extern-crates.md
Original file line number Diff line number Diff line change
Expand Up @@ -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;

Expand All @@ -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
Expand Down
9 changes: 5 additions & 4 deletions src/items/external-blocks.md
Original file line number Diff line number Diff line change
Expand Up @@ -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" { }
```
Expand Down Expand Up @@ -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, ...);
}
Expand Down Expand Up @@ -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 {
Expand Down Expand Up @@ -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();
Expand Down Expand Up @@ -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
6 changes: 5 additions & 1 deletion src/items/functions.md
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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 */
Expand Down Expand Up @@ -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) {
Expand Down
3 changes: 2 additions & 1 deletion src/items/generics.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
Expand Down
3 changes: 3 additions & 0 deletions src/items/modules.md
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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"]
Expand All @@ -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 {
Expand Down
16 changes: 10 additions & 6 deletions src/items/unions.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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);
}
```
Expand Down
9 changes: 7 additions & 2 deletions src/items/use-declarations.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 {}
}

Expand All @@ -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].
Expand Down
Loading