diff --git a/docs/authoring.md b/docs/authoring.md index 93cc9cf28..a37f7b214 100644 --- a/docs/authoring.md +++ b/docs/authoring.md @@ -167,9 +167,12 @@ Admonitions use a style similar to GitHub-flavored markdown, where the style nam ```markdown > [!WARNING] > This is a warning. + +> [!NOTE] +> This is a note. ``` -All this does is apply a CSS class to the blockquote. You should define the color or style of the rule in the [`theme/reference.css`](https://github.com/rust-lang/reference/blob/master/theme/reference.css) file if it isn't already defined. +The color and styling is defined in [`theme/reference.css`](https://github.com/rust-lang/reference/blob/master/theme/reference.css) and the transformation and icons are in [`mdbook-spec/src/lib.rs`](https://github.com/rust-lang/reference/blob/HEAD/mdbook-spec/src/lib.rs). ## Style diff --git a/mdbook-spec/src/lib.rs b/mdbook-spec/src/lib.rs index e52ca400e..7a624d9a5 100644 --- a/mdbook-spec/src/lib.rs +++ b/mdbook-spec/src/lib.rs @@ -144,11 +144,10 @@ impl Spec { /// > ... /// ``` /// - /// This will add a `
` around the blockquote so that - /// it can be styled differently. Any text between the brackets that can - /// be a CSS class is valid. The actual styling needs to be added in a CSS - /// file. - fn admonitions(&self, chapter: &Chapter) -> String { + /// This will add a `
` around the + /// blockquote so that it can be styled differently, and injects an icon. + /// The actual styling needs to be added in the `reference.css` CSS file. + fn admonitions(&self, chapter: &Chapter, diag: &mut Diagnostics) -> String { ADMONITION_RE .replace_all(&chapter.content, |caps: &Captures<'_>| { let lower = caps["admon"].to_lowercase(); @@ -156,10 +155,27 @@ impl Spec { let blockquote = &caps["blockquote"]; let initial_spaces = blockquote.chars().position(|ch| ch != ' ').unwrap_or(0); let space = &blockquote[..initial_spaces]; + // These icons are from GitHub, MIT License, see https://github.com/primer/octicons + let svg = match lower.as_str() { + "note" => "", + "warning" => "", + _ => { + warn_or_err!( + diag, + "admonition `{lower}` in {:?} is incorrect or not yet supported", + chapter.path.as_ref().unwrap() + ); + "" + } + }; format!( - "{space}
\n\ + "{space}
\n\ \n\ - {space}> ***{term}:***\n\ + {space}>

\ + \ + {svg}\ + {term}

\n\ + {space} >\n\ {blockquote}\n\ \n\ {space}
\n", @@ -226,7 +242,7 @@ impl Preprocessor for Spec { if ch.is_draft_chapter() { return; } - ch.content = self.admonitions(&ch); + ch.content = self.admonitions(&ch, &mut diag); ch.content = self.auto_link_references(&ch, &rules); ch.content = self.render_rule_definitions(&ch.content, &tests, &git_ref); if ch.name == "Test summary" { diff --git a/src/attributes.md b/src/attributes.md index 6d286c60d..d81e50ced 100644 --- a/src/attributes.md +++ b/src/attributes.md @@ -227,8 +227,8 @@ struct S { pub fn f() {} ``` -> Note: `rustc` currently recognizes the tools "clippy", "rustfmt", "diagnostic", -> "miri" and "rust_analyzer". +> [!NOTE] +> `rustc` currently recognizes the tools "clippy", "rustfmt", "diagnostic", "miri" and "rust_analyzer". r[attributes.builtin] ## Built-in attributes index diff --git a/src/attributes/codegen.md b/src/attributes/codegen.md index c309cd2a1..aa5e70617 100644 --- a/src/attributes/codegen.md +++ b/src/attributes/codegen.md @@ -26,9 +26,8 @@ The *`inline` [attribute]* suggests that a copy of the attributed function should be placed in the caller, rather than generating code to call the function where it is defined. -> ***Note***: The `rustc` compiler automatically inlines functions based on -> internal heuristics. Incorrectly inlining functions can make the program -> slower, so this attribute should be used with care. +> [!NOTE] +> The `rustc` compiler automatically inlines functions based on internal heuristics. Incorrectly inlining functions can make the program slower, so this attribute should be used with care. r[attributes.codegen.inline.modes] There are three ways to use the inline attribute: @@ -39,8 +38,8 @@ There are three ways to use the inline attribute: * `#[inline(never)]` *suggests* that an inline expansion should never be performed. -> ***Note***: `#[inline]` in every form is a hint, with no *requirements* -> on the language to place a copy of the attributed function in the caller. +> [!NOTE] +> `#[inline]` in every form is a hint, with no *requirements* on the language to place a copy of the attributed function in the caller. r[attributes.codegen.cold] ### The `cold` attribute @@ -229,8 +228,8 @@ Reference Manual], or elsewhere on [developer.arm.com]. [ARM Architecture Reference Manual]: https://developer.arm.com/documentation/ddi0487/latest [developer.arm.com]: https://developer.arm.com -> ***Note***: The following pairs of features should both be marked as enabled -> or disabled together if used: +> [!NOTE] +> The following pairs of features should both be marked as enabled or disabled together if used: > - `paca` and `pacg`, which LLVM currently implements as one feature. @@ -390,10 +389,8 @@ r[attributes.codegen.target_feature.remark-rt] See the [`is_x86_feature_detected`] or [`is_aarch64_feature_detected`] macros in the standard library for runtime feature detection on these platforms. -> Note: `rustc` has a default set of features enabled for each target and CPU. -> The CPU may be chosen with the [`-C target-cpu`] flag. Individual features -> may be enabled or disabled for an entire crate with the -> [`-C target-feature`] flag. +> [!NOTE] +> `rustc` has a default set of features enabled for each target and CPU. The CPU may be chosen with the [`-C target-cpu`] flag. Individual features may be enabled or disabled for an entire crate with the [`-C target-feature`] flag. r[attributes.codegen.track_caller] ## The `track_caller` attribute @@ -427,11 +424,11 @@ fn f() { } ``` -> Note: `core` provides [`core::panic::Location::caller`] for observing caller locations. It wraps -> the [`core::intrinsics::caller_location`] intrinsic implemented by `rustc`. +> [!NOTE] +> `core` provides [`core::panic::Location::caller`] for observing caller locations. It wraps the [`core::intrinsics::caller_location`] intrinsic implemented by `rustc`. -> Note: because the resulting `Location` is a hint, an implementation may halt its walk up the stack -> early. See [Limitations](#limitations) for important caveats. +> [!NOTE] +> Because the resulting `Location` is a hint, an implementation may halt its walk up the stack early. See [Limitations](#limitations) for important caveats. #### Examples @@ -504,12 +501,8 @@ appears to observers to have been called at the attributed function's definition caller information across virtual calls. A common example of this coercion is the creation of a trait object whose methods are attributed. -> Note: The aforementioned shim for function pointers is necessary because `rustc` implements -> `track_caller` in a codegen context by appending an implicit parameter to the function ABI, but -> this would be unsound for an indirect call because the parameter is not a part of the function's -> type and a given function pointer type may or may not refer to a function with the attribute. The -> creation of a shim hides the implicit parameter from callers of the function pointer, preserving -> soundness. +> [!NOTE] +> The aforementioned shim for function pointers is necessary because `rustc` implements `track_caller` in a codegen context by appending an implicit parameter to the function ABI, but this would be unsound for an indirect call because the parameter is not a part of the function's type and a given function pointer type may or may not refer to a function with the attribute. The creation of a shim hides the implicit parameter from callers of the function pointer, preserving soundness. [_MetaListNameValueStr_]: ../attributes.md#meta-item-attribute-syntax [`-C target-cpu`]: ../../rustc/codegen-options/index.html#target-cpu diff --git a/src/attributes/debugger.md b/src/attributes/debugger.md index 1dfce1ce7..ecd1b951d 100644 --- a/src/attributes/debugger.md +++ b/src/attributes/debugger.md @@ -173,7 +173,8 @@ r[attributes.debugger.collapse_debuginfo.default] The `external` behavior is the default for macros that don't have this attribute, unless they are built-in macros. For built-in macros the default is `yes`. -> **Note**: `rustc` has a `-C collapse-macro-debuginfo` CLI option to override both the default collapsing behavior and `#[collapse_debuginfo]` attributes. +> [!NOTE] +> `rustc` has a `-C collapse-macro-debuginfo` CLI option to override both the default collapsing behavior and `#[collapse_debuginfo]` attributes. ```rust #[collapse_debuginfo(yes)] diff --git a/src/attributes/diagnostics.md b/src/attributes/diagnostics.md index 0f1723fa9..e03971b4c 100644 --- a/src/attributes/diagnostics.md +++ b/src/attributes/diagnostics.md @@ -37,8 +37,8 @@ r[attributes.diagnostics.lint.forbid] * `#[forbid(C)]` is the same as `deny(C)`, but also forbids changing the lint level afterwards, -> Note: The lint checks supported by `rustc` can be found via `rustc -W help`, -> along with their default settings and are documented in the [rustc book]. +> [!NOTE] +> The lint checks supported by `rustc` can be found via `rustc -W help`, along with their default settings and are documented in the [rustc book]. ```rust pub mod m1 { @@ -98,9 +98,8 @@ pub mod m3 { } ``` -> Note: `rustc` allows setting lint levels on the -> [command-line][rustc-lint-cli], and also supports [setting -> caps][rustc-lint-caps] on the lints that are reported. +> [!NOTE] +> `rustc` allows setting lint levels on the [command-line][rustc-lint-cli], and also supports [setting caps][rustc-lint-caps] on the lints that are reported. r[attributes.diagnostics.lint.reason] ### Lint Reasons @@ -222,8 +221,8 @@ pub fn another_example() { } ``` -> Note: The behavior of `#[expect(unfulfilled_lint_expectations)]` is currently -> defined to always generate the `unfulfilled_lint_expectations` lint. +> [!NOTE] +> The behavior of `#[expect(unfulfilled_lint_expectations)]` is currently defined to always generate the `unfulfilled_lint_expectations` lint. r[attributes.diagnostics.lint.group] ### Lint groups @@ -297,7 +296,8 @@ fn foo() { } ``` -> Note: `rustc` currently recognizes the tool lints for "[clippy]" and "[rustdoc]". +> [!NOTE] +> `rustc` currently recognizes the tool lints for "[clippy]" and "[rustdoc]". r[attributes.diagnostics.deprecated] ## The `deprecated` attribute @@ -433,10 +433,8 @@ impl Trait for i32 { r[attributes.diagnostics.must_use.trait-impl-function] When used on a function in a trait implementation, the attribute does nothing. -> Note: Trivial no-op expressions containing the value will not violate the -> lint. Examples include wrapping the value in a type that does not implement -> [`Drop`] and then not using that type and being the final expression of a -> [block expression] that is not used. +> [!NOTE] +> Trivial no-op expressions containing the value will not violate the lint. Examples include wrapping the value in a type that does not implement [`Drop`] and then not using that type and being the final expression of a [block expression] that is not used. > > ```rust > #[must_use] @@ -452,8 +450,8 @@ When used on a function in a trait implementation, the attribute does nothing. > }; > ``` -> Note: It is idiomatic to use a [let statement] with a pattern of `_` -> when a must-used value is purposely discarded. +> [!NOTE] +> It is idiomatic to use a [let statement] with a pattern of `_` when a must-used value is purposely discarded. > > ```rust > #[must_use] @@ -558,7 +556,8 @@ r[attributes.diagnostic.do_not_recommend] r[attributes.diagnostic.do_not_recommend.intro] The `#[diagnostic::do_not_recommend]` attribute is a hint to the compiler to not show the annotated trait implementation as part of a diagnostic message. -> **Note**: Suppressing the recommendation can be useful if you know that the recommendation would normally not be useful to the programmer. This often occurs with broad, blanket impls. The recommendation may send the programmer down the wrong path, or the trait implementation may be an internal detail that you don't want to expose, or the bounds may not be able to be satisfied by the programmer. +> [!NOTE] +> Suppressing the recommendation can be useful if you know that the recommendation would normally not be useful to the programmer. This often occurs with broad, blanket impls. The recommendation may send the programmer down the wrong path, or the trait implementation may be an internal detail that you don't want to expose, or the bounds may not be able to be satisfied by the programmer. > > For example, in an error message about a type not implementing a required trait, the compiler may find a trait implementation that would satisfy the requirements if it weren't for specific bounds in the trait implementation. The compiler may tell the user that there is an impl, but the problem is the bounds in the trait implementation. The `#[diagnostic::do_not_recommend]` attribute can be used to tell the compiler to *not* tell the user about the trait implementation, and instead simply tell the user the type doesn't implement the required trait. diff --git a/src/attributes/limits.md b/src/attributes/limits.md index 37000c44b..9b4db515e 100644 --- a/src/attributes/limits.md +++ b/src/attributes/limits.md @@ -16,7 +16,8 @@ r[attributes.limits.recursion_limit.syntax] It uses the [_MetaNameValueStr_] syntax to specify the recursion depth. -> Note: The default in `rustc` is 128. +> [!NOTE] +> The default in `rustc` is 128. ```rust,compile_fail #![recursion_limit = "4"] @@ -44,7 +45,8 @@ r[attributes.limits.type_length_limit] ## The `type_length_limit` attribute -> **Note**: This limit is only enforced when the nightly `-Zenforce-type-length-limit` flag is active. +> [!NOTE] +> This limit is only enforced when the nightly `-Zenforce-type-length-limit` flag is active. > > For more information, see . @@ -56,7 +58,8 @@ r[attributes.limits.type_length_limit.syntax] It is applied at the [crate] level, and uses the [_MetaNameValueStr_] syntax to set the limit based on the number of type substitutions. -> Note: The default in `rustc` is 1048576. +> [!NOTE] +> The default in `rustc` is 1048576. ```rust,ignore #![type_length_limit = "4"] diff --git a/src/attributes/testing.md b/src/attributes/testing.md index 1c37c6d2f..a11a6b371 100644 --- a/src/attributes/testing.md +++ b/src/attributes/testing.md @@ -26,8 +26,8 @@ Test functions must be free, monomorphic functions that take no arguments, and t -> Note: The test mode is enabled by passing the `--test` argument to `rustc` -> or using `cargo test`. +> [!NOTE] +> The test mode is enabled by passing the `--test` argument to `rustc` or using `cargo test`. r[attributes.testing.test.success] The test harness calls the returned value's [`report`] method, and classifies the test as passed or failed depending on whether the resulting [`ExitCode`] represents successful termination. @@ -69,8 +69,8 @@ fn mytest() { } ``` -> **Note**: The `rustc` test harness supports the `--include-ignored` flag to -> force ignored tests to be run. +> [!NOTE] +> The `rustc` test harness supports the `--include-ignored` flag to force ignored tests to be run. r[attributes.testing.should_panic] ## The `should_panic` attribute diff --git a/src/behavior-considered-undefined.md b/src/behavior-considered-undefined.md index a11e67aec..d2a7d72fc 100644 --- a/src/behavior-considered-undefined.md +++ b/src/behavior-considered-undefined.md @@ -101,11 +101,8 @@ r[undefined.runtime] * For assumptions specifically related to unwinding, see the [panic documentation][unwinding-ffi]. * The runtime assumes that a Rust stack frame is not deallocated without executing destructors for local variables owned by the stack frame. This assumption can be violated by C functions like `longjmp`. -> **Note**: Undefined behavior affects the entire program. For example, calling -> a function in C that exhibits undefined behavior of C means your entire -> program contains undefined behaviour that can also affect the Rust code. And -> vice versa, undefined behavior in Rust can cause adverse affects on code -> executed by any FFI calls to other languages. +> [!NOTE] +> Undefined behavior affects the entire program. For example, calling a function in C that exhibits undefined behavior of C means your entire program contains undefined behaviour that can also affect the Rust code. And vice versa, undefined behavior in Rust can cause adverse affects on code executed by any FFI calls to other languages. r[undefined.pointed-to] ### Pointed-to bytes @@ -237,8 +234,8 @@ r[undefined.validity.valid-range] * If a type has a custom range of a valid values, then a valid value must be in that range. In the standard library, this affects [`NonNull`] and [`NonZero`]. - > **Note**: `rustc` achieves this with the unstable - > `rustc_layout_scalar_valid_range_*` attributes. + > [!NOTE] + > `rustc` achieves this with the unstable `rustc_layout_scalar_valid_range_*` attributes. r[undefined.validity.undef] **Note:** Uninitialized memory is also implicitly invalid for any type that has diff --git a/src/comments.md b/src/comments.md index 6b4a954e4..d66b6eb23 100644 --- a/src/comments.md +++ b/src/comments.md @@ -71,13 +71,11 @@ modules that occupy a source file. r[comments.doc.bare-crs] The character `U+000D` (CR) is not allowed in doc comments. -> **Note**: It is conventional for doc comments to contain Markdown, as expected by -> `rustdoc`. However, the comment syntax does not respect any internal Markdown. -> ``/** `glob = "*/*.rs";` */`` terminates the comment at the first `*/`, and the -> remaining code would cause a syntax error. This slightly limits the content of -> block doc comments compared to line doc comments. +> [!NOTE] +> It is conventional for doc comments to contain Markdown, as expected by `rustdoc`. However, the comment syntax does not respect any internal Markdown. ``/** `glob = "*/*.rs";` */`` terminates the comment at the first `*/`, and the remaining code would cause a syntax error. This slightly limits the content of block doc comments compared to line doc comments. -> **Note**: The sequence `U+000D` (CR) immediately followed by `U+000A` (LF) would have been previously transformed into a single `U+000A` (LF). +> [!NOTE] +> The sequence `U+000D` (CR) immediately followed by `U+000A` (LF) would have been previously transformed into a single `U+000A` (LF). ## Examples diff --git a/src/conditional-compilation.md b/src/conditional-compilation.md index fb081f55c..a214326e2 100644 --- a/src/conditional-compilation.md +++ b/src/conditional-compilation.md @@ -58,7 +58,8 @@ Names are written as a single identifier, such as `unix`. r[cfg.option-key-value] Key-value pairs are written as an identifier, `=`, and then a string, such as `target_arch = "x86_64"`. -> **Note**: Whitespace around the `=` is ignored, so `foo="bar"` and `foo = "bar"` are equivalent. +> [!NOTE] +> Whitespace around the `=` is ignored, so `foo="bar"` and `foo = "bar"` are equivalent. r[cfg.option-key-uniqueness] Keys do not need to be unique. For example, both `feature = "std"` and `feature = "serde"` can be set at the same time. @@ -80,12 +81,11 @@ r[cfg.options.crate] It is not possible to set a configuration option from within the source code of the crate being compiled. -> **Note**: For `rustc`, arbitrary-set configuration options are set using the -> [`--cfg`] flag. Configuration values for a specified target can be displayed with `rustc --print cfg --target $TARGET`. +> [!NOTE] +> For `rustc`, arbitrary-set configuration options are set using the [`--cfg`] flag. Configuration values for a specified target can be displayed with `rustc --print cfg --target $TARGET`. -> **Note**: Configuration options with the key `feature` are a convention used -> by [Cargo][cargo-feature] for specifying compile-time options and optional -> dependencies. +> [!NOTE] +> Configuration options with the key `feature` are a convention used by [Cargo][cargo-feature] for specifying compile-time options and optional dependencies. r[cfg.target_arch] ### `target_arch` @@ -422,10 +422,8 @@ fn bewitched() {} fn bewitched() {} ``` -> **Note**: The `cfg_attr` can expand to another `cfg_attr`. For example, -> `#[cfg_attr(target_os = "linux", cfg_attr(feature = "multithreaded", some_other_attribute))]` -> is valid. This example would be equivalent to -> `#[cfg_attr(all(target_os = "linux", feature ="multithreaded"), some_other_attribute)]`. +> [!NOTE] +> The `cfg_attr` can expand to another `cfg_attr`. For example, `#[cfg_attr(target_os = "linux", cfg_attr(feature = "multithreaded", some_other_attribute))]` is valid. This example would be equivalent to `#[cfg_attr(all(target_os = "linux", feature ="multithreaded"), some_other_attribute)]`. r[cfg.cfg_attr.restriction] The `cfg_attr` attribute is allowed anywhere attributes are allowed. diff --git a/src/crates-and-source-files.md b/src/crates-and-source-files.md index 64bff1616..1ba86d63e 100644 --- a/src/crates-and-source-files.md +++ b/src/crates-and-source-files.md @@ -7,10 +7,8 @@ r[crate.syntax] >    [_InnerAttribute_]\*\ >    [_Item_]\* -> Note: Although Rust, like any other language, can be implemented by an -> interpreter as well as a compiler, the only existing implementation is a -> compiler, and the language has always been designed to be compiled. For these -> reasons, this section assumes a compiler. +> [!NOTE] +> Although Rust, like any other language, can be implemented by an interpreter as well as a compiler, the only existing implementation is a compiler, and the language has always been designed to be compiled. For these reasons, this section assumes a compiler. r[crate.compile-time] Rust's semantics obey a *phase distinction* between compile-time and @@ -60,7 +58,8 @@ r[crate.attributes] The anonymous crate module can have additional attributes that apply to the crate as a whole. -> **Note**: The file's contents may be preceded by a [shebang]. +> [!NOTE] +> The file's contents may be preceded by a [shebang]. ```rust // Specify the crate name. @@ -111,7 +110,8 @@ mod foo { use foo::bar as main; ``` -> **Note**: Types with implementations of [`Termination`] in the standard library include: +> [!NOTE] +> Types with implementations of [`Termination`] in the standard library include: > > * `()` > * [`!`] diff --git a/src/destructors.md b/src/destructors.md index 856e15d4b..5467c5abb 100644 --- a/src/destructors.md +++ b/src/destructors.md @@ -211,12 +211,8 @@ smallest scope that contains the expression and is one of the following: * The pattern-matching condition and consequent body of [`if let`] ([destructors.scope.temporary.edition2024]). * The entirety of the tail expression of a block ([destructors.scope.temporary.edition2024]). -> **Notes**: -> -> The [scrutinee] of a `match` expression is not a temporary scope, so -> temporaries in the scrutinee can be dropped after the `match` expression. For -> example, the temporary for `1` in `match 1 { ref mut z => z };` lives until -> the end of the statement. +> [!NOTE] +> The [scrutinee] of a `match` expression is not a temporary scope, so temporaries in the scrutinee can be dropped after the `match` expression. For example, the temporary for `1` in `match 1 { ref mut z => z };` lives until the end of the statement. r[destructors.scope.temporary.edition2024] > **Edition differences**: The 2024 edition added two new temporary scope narrowing rules: `if let` temporaries are dropped before the `else` block, and temporaries of tail expressions of blocks are dropped immediately after the tail expression is evaluated. @@ -315,8 +311,8 @@ r[destructors.scope.lifetime-extension] ### Temporary lifetime extension -> **Note**: The exact rules for temporary lifetime extension are subject to -> change. This is describing the current behavior only. +> [!NOTE] +> The exact rules for temporary lifetime extension are subject to change. This is describing the current behavior only. r[destructors.scope.lifetime-extension.let] The temporary scopes for expressions in `let` statements are sometimes @@ -432,8 +428,8 @@ r[destructors.manually-suppressing] and [`std::mem::ManuallyDrop`] provides a wrapper to prevent a variable or field from being dropped automatically. -> Note: Preventing a destructor from being run via [`std::mem::forget`] or other means is safe even if it has a type that isn't `'static`. -> Besides the places where destructors are guaranteed to run as defined by this document, types may *not* safely rely on a destructor being run for soundness. +> [!NOTE] +> Preventing a destructor from being run via [`std::mem::forget`] or other means is safe even if it has a type that isn't `'static`. Besides the places where destructors are guaranteed to run as defined by this document, types may *not* safely rely on a destructor being run for soundness. r[destructors.process-termination] ### Process termination without unwinding diff --git a/src/dynamically-sized-types.md b/src/dynamically-sized-types.md index e65d3e022..b30958ded 100644 --- a/src/dynamically-sized-types.md +++ b/src/dynamically-sized-types.md @@ -34,13 +34,13 @@ r[dynamic-sized.struct-field] last field; this makes the struct itself a DST. -> **Note**: [variables], function parameters, [const] items, and [static] items must be -`Sized`. +> [!NOTE] +> [Variables], function parameters, [const] items, and [static] items must be `Sized`. [sized]: special-types-and-traits.md#sized [Slices]: types/slice.md [trait objects]: types/trait-object.md [Pointer types]: types/pointer.md -[variables]: variables.md +[Variables]: variables.md [const]: items/constant-items.md [static]: items/static-items.md diff --git a/src/expressions.md b/src/expressions.md index 6de08086d..8827c9592 100644 --- a/src/expressions.md +++ b/src/expressions.md @@ -65,7 +65,8 @@ r[expr.structure] In this way, the structure of expressions dictates the structure of execution. Blocks are just another kind of expression, so blocks, statements, expressions, and blocks again can recursively nest inside each other to an arbitrary depth. -> **Note**: We give names to the operands of expressions so that we may discuss them, but these names are not stable and may be changed. +> [!NOTE] +> We give names to the operands of expressions so that we may discuss them, but these names are not stable and may be changed. r[expr.precedence] ## Expression precedence @@ -126,8 +127,8 @@ r[expr.operand-order.operands-before-primary] The operands of these expressions are evaluated prior to applying the effects of the expression. Expressions taking multiple operands are evaluated left to right as written in the source code. -> **Note**: Which subexpressions are the operands of an expression is -> determined by expression precedence as per the previous section. +> [!NOTE] +> Which subexpressions are the operands of an expression is determined by expression precedence as per the previous section. For example, the two `next` method calls will always be called in the same order: @@ -142,7 +143,8 @@ assert_eq!( ); ``` -> **Note**: Since this is applied recursively, these expressions are also evaluated from innermost to outermost, ignoring siblings until there are no inner subexpressions. +> [!NOTE] +> Since this is applied recursively, these expressions are also evaluated from innermost to outermost, ignoring siblings until there are no inner subexpressions. r[expr.place-value] ## Place Expressions and Value Expressions @@ -178,7 +180,8 @@ The following contexts are *place expression* contexts: expression. * The base of a [functional update] struct expression. -> Note: Historically, place expressions were called *lvalues* and value expressions were called *rvalues*. +> [!NOTE] +> Historically, place expressions were called *lvalues* and value expressions were called *rvalues*. r[expr.place-value.assignee] An *assignee expression* is an expression that appears in the left operand of an [assignment][assign] expression. diff --git a/src/expressions/block-expr.md b/src/expressions/block-expr.md index 3afebefe5..3d6936bc8 100644 --- a/src/expressions/block-expr.md +++ b/src/expressions/block-expr.md @@ -59,13 +59,14 @@ let five: i32 = { assert_eq!(5, five); ``` -> Note: As a control flow expression, if a block expression is the outer expression of an expression statement, the expected type is `()` unless it is followed immediately by a semicolon. +> [!NOTE] +> As a control flow expression, if a block expression is the outer expression of an expression statement, the expected type is `()` unless it is followed immediately by a semicolon. r[expr.block.value] Blocks are always [value expressions] and evaluate the last operand in value expression context. -> **Note**: This can be used to force moving a value if really needed. -> For example, the following example fails on the call to `consume_self` because the struct was moved out of `s` in the block expression. +> [!NOTE] +> This can be used to force moving a value if really needed. For example, the following example fails on the call to `consume_self` because the struct was moved out of `s` in the block expression. > > ```rust,compile_fail > struct Struct; @@ -110,7 +111,8 @@ Whereas closures return a type that implements one or more of the [`std::ops::Fn r[expr.block.async.layout-unspecified] The actual data format for this type is unspecified. -> **Note:** The future type that rustc generates is roughly equivalent to an enum with one variant per `await` point, where each variant stores the data needed to resume from its corresponding point. +> [!NOTE] +> The future type that rustc generates is roughly equivalent to an enum with one variant per `await` point, where each variant stores the data needed to resume from its corresponding point. > **Edition differences**: Async blocks are only available beginning with Rust 2018. diff --git a/src/expressions/call-expr.md b/src/expressions/call-expr.md index 872a5d467..9f3f6bf76 100644 --- a/src/expressions/call-expr.md +++ b/src/expressions/call-expr.md @@ -44,9 +44,8 @@ All function calls are sugar for a more explicit [fully-qualified syntax]. r[expr.call.desugar.ambiguity] Function calls may need to be fully qualified, depending on the ambiguity of a call in light of in-scope items. -> **Note**: In the past, the terms "Unambiguous Function Call Syntax", "Universal Function Call Syntax", or "UFCS", have been used in documentation, issues, RFCs, and other community writings. -> However, these terms lack descriptive power and potentially confuse the issue at hand. -> We mention them here for searchability's sake. +> [!NOTE] +> In the past, the terms "Unambiguous Function Call Syntax", "Universal Function Call Syntax", or "UFCS", have been used in documentation, issues, RFCs, and other community writings. However, these terms lack descriptive power and potentially confuse the issue at hand. We mention them here for searchability's sake. r[expr.call.desugar.limits] Several situations often occur which result in ambiguities about the receiver or referent of method or associated function calls. diff --git a/src/expressions/field-expr.md b/src/expressions/field-expr.md index 50d493c90..b90657be7 100644 --- a/src/expressions/field-expr.md +++ b/src/expressions/field-expr.md @@ -19,7 +19,8 @@ r[expr.field.not-method-call] Field expressions cannot be followed by a parenthetical comma-separated list of expressions, as that is instead parsed as a [method call expression]. That is, they cannot be the function operand of a [call expression]. -> **Note**: Wrap the field expression in a [parenthesized expression] to use it in a call expression. +> [!NOTE] +> Wrap the field expression in a [parenthesized expression] to use it in a call expression. > > ```rust > # struct HoldsCallable { callable: F } diff --git a/src/expressions/literal-expr.md b/src/expressions/literal-expr.md index 21e465c18..78cc959fe 100644 --- a/src/expressions/literal-expr.md +++ b/src/expressions/literal-expr.md @@ -34,7 +34,8 @@ Each of the lexical [literal][literal tokens] forms described earlier can make u r[expr.literal.string-representation] In the descriptions below, the _string representation_ of a token is the sequence of characters from the input which matched the token's production in a *Lexer* grammar snippet. -> **Note**: this string representation never includes a character `U+000D` (CR) immediately followed by `U+000A` (LF): this pair would have been previously transformed into a single `U+000A` (LF). +> [!NOTE] +> This string representation never includes a character `U+000D` (CR) immediately followed by `U+000A` (LF): this pair would have been previously transformed into a single `U+000A` (LF). r[expr.literal.escape] ## Escapes @@ -75,7 +76,8 @@ The escape sequence consists of `\x` followed by two hexadecimal digits. The escaped value is the character whose [Unicode scalar value] is the result of interpreting the final two characters in the escape sequence as a hexadecimal integer, as if by [`u8::from_str_radix`] with radix 16. -> **Note**: the escaped value therefore has a [Unicode scalar value] in the range of [`u8`][numeric types]. +> [!NOTE] +> The escaped value therefore has a [Unicode scalar value] in the range of [`u8`][numeric types]. r[expr.literal.escape.hex-ascii] ### 7-bit escapes @@ -91,7 +93,8 @@ The escape sequence consists of `\u{`, followed by a sequence of characters each The escaped value is the character whose [Unicode scalar value] is the result of interpreting the hexadecimal digits contained in the escape sequence as a hexadecimal integer, as if by [`u32::from_str_radix`] with radix 16. -> **Note**: the permitted forms of a [CHAR_LITERAL] or [STRING_LITERAL] token ensure that there is such a character. +> [!NOTE] +> The permitted forms of a [CHAR_LITERAL] or [STRING_LITERAL] token ensure that there is such a character. r[expr.literal.continuation] ### String continuation escapes @@ -101,8 +104,9 @@ For this purpose, the whitespace characters are `U+0009` (HT), `U+000A` (LF), `U The escaped value is an empty sequence of characters. -> **Note**: The effect of this form of escape is that a string continuation skips following whitespace, including additional newlines. -> Thus `a`, `b` and `c` are equal: +> [!NOTE] +> The effect of this form of escape is that a string continuation skips following whitespace, including additional newlines. Thus `a`, `b` and `c` are equal: +> > ```rust > let a = "foobar"; > let b = "foo\ @@ -115,10 +119,7 @@ The escaped value is an empty sequence of characters. > assert_eq!(b, c); > ``` > -> Skipping additional newlines (as in example c) is potentially confusing and unexpected. -> This behavior may be adjusted in the future. -> Until a decision is made, it is recommended to avoid relying on skipping multiple newlines with line continuations. -> See [this issue](https://github.com/rust-lang/reference/pull/1042) for more information. +> Skipping additional newlines (as in example c) is potentially confusing and unexpected. This behavior may be adjusted in the future. Until a decision is made, it is recommended to avoid relying on skipping multiple newlines with line continuations. See [this issue](https://github.com/rust-lang/reference/pull/1042) for more information. r[expr.literal.char] ## Character literal expressions @@ -150,7 +151,8 @@ r[expr.literal.char.single] r[expr.literal.char.result] The expression's value is the [`char`][textual types] corresponding to the represented character's [Unicode scalar value]. -> **Note**: the permitted forms of a [CHAR_LITERAL] token ensure that these rules always produce a single character. +> [!NOTE] +> The permitted forms of a [CHAR_LITERAL] token ensure that these rules always produce a single character. Examples of character literal expressions: @@ -238,7 +240,8 @@ r[expr.literal.byte-char.single] r[expr.literal.byte-char.result] The expression's value is the represented character's [Unicode scalar value]. -> **Note**: the permitted forms of a [BYTE_LITERAL] token ensure that these rules always produce a single character, whose Unicode scalar value is in the range of [`u8`][numeric types]. +> [!NOTE] +> The permitted forms of a [BYTE_LITERAL] token ensure that these rules always produce a single character, whose Unicode scalar value is in the range of [`u8`][numeric types]. Examples of byte literal expressions: @@ -283,7 +286,8 @@ r[expr.literal.byte-string.raw] r[expr.literal.byte-string.result] The expression's value is a reference to a statically allocated array containing the [Unicode scalar values] of the characters in the represented string, in the same order. -> **Note**: the permitted forms of [BYTE_STRING_LITERAL] and [RAW_BYTE_STRING_LITERAL] tokens ensure that these rules always produce array element values in the range of [`u8`][numeric types]. +> [!NOTE] +> The permitted forms of [BYTE_STRING_LITERAL] and [RAW_BYTE_STRING_LITERAL] tokens ensure that these rules always produce array element values in the range of [`u8`][numeric types]. Examples of byte string literal expressions: @@ -329,7 +333,8 @@ The sequence of items is converted to a sequence of bytes as follows: r[expr.literal.c-string.raw] * If the token is a [RAW_C_STRING_LITERAL], the represented bytes are the UTF-8 encoding of the literal content. -> **Note**: the permitted forms of [C_STRING_LITERAL] and [RAW_C_STRING_LITERAL] tokens ensure that the represented bytes never include a null byte. +> [!NOTE] +> The permitted forms of [C_STRING_LITERAL] and [RAW_C_STRING_LITERAL] tokens ensure that the represented bytes never include a null byte. r[expr.literal.c-string.result] The expression's value is a reference to a statically allocated [CStr] whose array of bytes contains the represented bytes followed by a null byte. @@ -423,11 +428,11 @@ If the value does not fit in `u128`, it is a compiler error. r[expr.literal.int.cast] * The `u128` value is converted to the expression's type via a [numeric cast]. -> **Note**: The final cast will truncate the value of the literal if it does not fit in the expression's type. -> `rustc` includes a [lint check] named `overflowing_literals`, defaulting to `deny`, which rejects expressions where this occurs. +> [!NOTE] +> The final cast will truncate the value of the literal if it does not fit in the expression's type. `rustc` includes a [lint check] named `overflowing_literals`, defaulting to `deny`, which rejects expressions where this occurs. -> **Note**: `-1i8`, for example, is an application of the [negation operator] to the literal expression `1i8`, not a single integer literal expression. -> See [Overflow] for notes on representing the most negative value for a signed type. +> [!NOTE] +> `-1i8`, for example, is an application of the [negation operator] to the literal expression `1i8`, not a single integer literal expression. See [Overflow] for notes on representing the most negative value for a signed type. r[expr.literal.float] ## Floating-point literal expressions @@ -475,11 +480,11 @@ r[expr.literal.float.separators-stripped] r[expr.literal.float.value] * The string is converted to the expression's type as if by [`f32::from_str`] or [`f64::from_str`]. -> **Note**: `-1.0`, for example, is an application of the [negation operator] to the literal expression `1.0`, not a single floating-point literal expression. +> [!NOTE] +> `-1.0`, for example, is an application of the [negation operator] to the literal expression `1.0`, not a single floating-point literal expression. -> **Note**: `inf` and `NaN` are not literal tokens. -> The [`f32::INFINITY`], [`f64::INFINITY`], [`f32::NAN`], and [`f64::NAN`] constants can be used instead of literal expressions. -> In `rustc`, a literal large enough to be evaluated as infinite will trigger the `overflowing_literals` lint check. +> [!NOTE] +> `inf` and `NaN` are not literal tokens. The [`f32::INFINITY`], [`f64::INFINITY`], [`f32::NAN`], and [`f64::NAN`] constants can be used instead of literal expressions. In `rustc`, a literal large enough to be evaluated as infinite will trigger the `overflowing_literals` lint check. r[expr.literal.bool] ## Boolean literal expressions diff --git a/src/expressions/loop-expr.md b/src/expressions/loop-expr.md index c60453143..c3e3c1529 100644 --- a/src/expressions/loop-expr.md +++ b/src/expressions/loop-expr.md @@ -218,8 +218,8 @@ r[expr.loop.for.lang-items] The variable names `next`, `iter`, and `val` are for exposition only, they do not actually have names the user can type. -> **Note**: that the outer `match` is used to ensure that any [temporary values] in `iter_expr` don't get dropped before the loop is finished. -> `next` is declared before being assigned because it results in types being inferred correctly more often. +> [!NOTE] +> The outer `match` is used to ensure that any [temporary values] in `iter_expr` don't get dropped before the loop is finished. `next` is declared before being assigned because it results in types being inferred correctly more often. r[expr.loop.label] ## Loop labels diff --git a/src/expressions/match-expr.md b/src/expressions/match-expr.md index 9c7fecf44..9071d7bef 100644 --- a/src/expressions/match-expr.md +++ b/src/expressions/match-expr.md @@ -91,8 +91,8 @@ match S(1, 2) { } ``` -> Note: The `2..=9` is a [Range Pattern], not a [Range Expression]. -> Thus, only those types of ranges supported by range patterns can be used in match arms. +> [!NOTE] +> The `2..=9` is a [Range Pattern], not a [Range Expression]. Thus, only those types of ranges supported by range patterns can be used in match arms. r[expr.match.or-patterns-restriction] Every binding in each `|` separated pattern must appear in all of the patterns in the arm. @@ -127,8 +127,8 @@ let message = match maybe_digit { }; ``` -> Note: Multiple matches using the `|` operator can cause the pattern guard and the side effects it has to execute multiple times. -> For example: +> [!NOTE] +> Multiple matches using the `|` operator can cause the pattern guard and the side effects it has to execute multiple times. For example: > > ```rust > # use std::cell::Cell; diff --git a/src/expressions/method-call-expr.md b/src/expressions/method-call-expr.md index f6e748328..f35e9210a 100644 --- a/src/expressions/method-call-expr.md +++ b/src/expressions/method-call-expr.md @@ -40,8 +40,8 @@ Then, for each candidate type `T`, search for a [visible] method with a receiver If `T` is a type parameter, methods provided by trait bounds on `T` are looked up first. Then all remaining methods in scope are looked up. -> Note: the lookup is done for each type in order, which can occasionally lead to surprising results. -> The below code will print "In trait impl!", because `&self` methods are looked up first, the trait method is found before the struct's `&mut self` method is found. +> [!NOTE] +> The lookup is done for each type in order, which can occasionally lead to surprising results. The below code will print "In trait impl!", because `&self` methods are looked up first, the trait method is found before the struct's `&mut self` method is found. > > ```rust > struct Foo {} diff --git a/src/expressions/operator-expr.md b/src/expressions/operator-expr.md index ee92245da..5fc1a93ce 100644 --- a/src/expressions/operator-expr.md +++ b/src/expressions/operator-expr.md @@ -42,7 +42,8 @@ r[expr.operator.int-overflow.div] r[expr.operator.int-overflow.shift] * Using `<<` or `>>` where the right-hand argument is greater than or equal to the number of bits in the type of the left-hand argument, or is negative. -> **Note**: The exception for literal expressions behind unary `-` means that forms such as `-128_i8` or `let j: i8 = -(128)` never cause a panic and have the expected value of -128. +> [!NOTE] +> The exception for literal expressions behind unary `-` means that forms such as `-128_i8` or `let j: i8 = -(128)` never cause a panic and have the expected value of -128. > > In these cases, the literal expression already has the most negative value for its type (for example, `128_i8` has the value -128) because integer literals are truncated to their type per the description in [Integer literal expressions][literal expression]. > @@ -713,7 +714,8 @@ The assigned value operand is evaluated first, followed by the assignee expressi r[expr.assign.destructring-order] For destructuring assignment, subexpressions of the assignee expression are evaluated left-to-right. -> **Note**: This is different than other expressions in that the right operand is evaluated before the left one. +> [!NOTE] +> This is different than other expressions in that the right operand is evaluated before the left one. r[expr.assign.drop-target] It then has the effect of first [dropping] the value at the assigned place, unless the place is an uninitialized local variable or an uninitialized field of a local variable. @@ -837,7 +839,8 @@ r[expr.compound-assign.primitive-order] If both types are primitives, then the modifying operand will be evaluated first followed by the assigned operand. It will then set the value of the assigned operand's place to the value of performing the operation of the operator with the values of the assigned operand and modifying operand. -> **Note**: This is different than other expressions in that the right operand is evaluated before the left one. +> [!NOTE] +> This is different than other expressions in that the right operand is evaluated before the left one. r[expr.compound-assign.trait] Otherwise, this expression is syntactic sugar for calling the function of the overloading compound assignment trait of the operator (see the table earlier in this chapter). diff --git a/src/expressions/tuple-expr.md b/src/expressions/tuple-expr.md index d1acab412..dce2df104 100644 --- a/src/expressions/tuple-expr.md +++ b/src/expressions/tuple-expr.md @@ -83,9 +83,11 @@ assert_eq!(point.0, 1.0); assert_eq!(point.1, 0.0); ``` -> **Note**: Unlike field access expressions, tuple index expressions can be the function operand of a [call expression] as it cannot be confused with a method call since method names cannot be numbers. +> [!NOTE] +> Unlike field access expressions, tuple index expressions can be the function operand of a [call expression] as it cannot be confused with a method call since method names cannot be numbers. -> **Note**: Although arrays and slices also have elements, you must use an [array or slice indexing expression] or a [slice pattern] to access their elements. +> [!NOTE] +> Although arrays and slices also have elements, you must use an [array or slice indexing expression] or a [slice pattern] to access their elements. [_Expression_]: ../expressions.md [array or slice indexing expression]: array-expr.md#array-and-slice-indexing-expressions diff --git a/src/identifiers.md b/src/identifiers.md index 038194450..779855f59 100644 --- a/src/identifiers.md +++ b/src/identifiers.md @@ -35,7 +35,8 @@ The profile used from UAX #31 is: with the additional constraint that a single underscore character is not an identifier. -> **Note**: Identifiers starting with an underscore are typically used to indicate an identifier that is intentionally unused, and will silence the unused warning in `rustc`. +> [!NOTE] +> Identifiers starting with an underscore are typically used to indicate an identifier that is intentionally unused, and will silence the unused warning in `rustc`. r[ident.keyword] Identifiers may not be a [strict] or [reserved] keyword without the `r#` prefix described below in [raw identifiers](#raw-identifiers). diff --git a/src/inline-assembly.md b/src/inline-assembly.md index 39a129393..ba0b458d1 100644 --- a/src/inline-assembly.md +++ b/src/inline-assembly.md @@ -533,7 +533,7 @@ Here is the list of currently supported register classes: | s390x | `vreg` | `v[0-31]` | Only clobbers | | s390x | `areg` | `a[2-15]` | Only clobbers | -> **Notes**: +> [!NOTE] > - On x86 we treat `reg_byte` differently from `reg` because the compiler can allocate `al` and `ah` separately whereas `reg` reserves the whole register. > - On x86-64 the high byte registers (e.g. `ah`) are not available in the `reg_byte` register class. > - Some register classes are marked as "Only clobbers" which means that registers in these classes cannot be used for inputs or outputs, only clobbers of the form `out() _` or `lateout() _`. @@ -579,7 +579,8 @@ The availability of supported types for a particular register class may depend o | s390x | `vreg` | N/A | Only clobbers | | s390x | `areg` | N/A | Only clobbers | -> **Note**: For the purposes of the above table pointers, function pointers and `isize`/`usize` are treated as the equivalent integer type (`i16`/`i32`/`i64` depending on the target). +> [!NOTE] +> For the purposes of the above table pointers, function pointers and `isize`/`usize` are treated as the equivalent integer type (`i16`/`i32`/`i64` depending on the target). ```rust # #[cfg(target_arch = "x86_64")] { @@ -827,7 +828,7 @@ The supported modifiers are a subset of LLVM's (and GCC's) [asm template argumen | s390x | `reg_addr` | None | `%r1` | None | | s390x | `freg` | None | `%f0` | None | -> **Notes**: +> [!NOTE] > - on ARM `e` / `f`: this prints the low or high doubleword register name of a NEON quad (128-bit) register. > - on x86: our behavior for `reg` with no modifiers differs from what GCC does. > GCC will infer the modifier based on the operand value type, while we default to the full register size. @@ -939,7 +940,7 @@ The following ABIs can be used with `clobber_abi`: | LoongArch | `"C"`, `"system"` | `$r1`, `$r[4-20]`, `$f[0-23]` | | s390x | `"C"`, `"system"` | `r[0-5]`, `r14`, `f[0-7]`, `v[0-31]`, `a[2-15]` | -> Notes: +> [!NOTE] > - On AArch64 `x18` only included in the clobber list if it is not considered as a reserved register on the target. > - On RISC-V `x[16-17]` and `x[28-31]` only included in the clobber list if they are not considered as reserved registers on the target. @@ -1329,7 +1330,8 @@ r[asm.rules.x86-prefix-restriction] - The compiler is currently unable to detect this due to the way inline assembly is compiled, but may catch and reject this in the future. r[asm.rules.preserves_flags] -> **Note**: As a general rule, the flags covered by `preserves_flags` are those which are *not* preserved when performing a function call. +> [!NOTE] +> As a general rule, the flags covered by `preserves_flags` are those which are *not* preserved when performing a function call. r[asm.validity] ### Correctness and Validity diff --git a/src/input-format.md b/src/input-format.md index dee13465e..53e62ffcd 100644 --- a/src/input-format.md +++ b/src/input-format.md @@ -50,7 +50,8 @@ r[input.shebang.inner-attribute] As an exception, if the `#!` characters are followed (ignoring intervening [comments] or [whitespace]) by a `[` token, nothing is removed. This prevents an [inner attribute] at the start of a source file being removed. -> **Note**: The standard library [`include!`] macro applies byte order mark removal, CRLF normalization, and shebang removal to the file it reads. The [`include_str!`] and [`include_bytes!`] macros do not. +> [!NOTE] +> The standard library [`include!`] macro applies byte order mark removal, CRLF normalization, and shebang removal to the file it reads. The [`include_str!`] and [`include_bytes!`] macros do not. r[input.tokenization] ## Tokenization diff --git a/src/introduction.md b/src/introduction.md index 4cd205b1b..5c341d064 100644 --- a/src/introduction.md +++ b/src/introduction.md @@ -82,9 +82,10 @@ These conventions are documented here. > **Edition differences**: In the 2015 edition, this syntax is valid that is disallowed as of the 2018 edition. -* Notes that contain useful information about the state of the book or point out useful, but mostly out of scope, information are in blockquotes that start with the word "Note:" in **bold**. +* Notes that contain useful information about the state of the book or point out useful, but mostly out of scope, information are in note blocks. - > **Note**: This is an example note. + > [!NOTE] + > This is an example note. * Warnings that show unsound behavior in the language or possibly confusing interactions of language features are in a special warning box. diff --git a/src/items/associated-items.md b/src/items/associated-items.md index ea95c1890..bbecfb676 100644 --- a/src/items/associated-items.md +++ b/src/items/associated-items.md @@ -156,7 +156,8 @@ Shorthand | Equivalent `&'lifetime self` | `self: &'lifetime Self` `&'lifetime mut self` | `self: &'lifetime mut Self` -> **Note**: Lifetimes can be, and usually are, elided with this shorthand. +> [!NOTE] +> Lifetimes can be, and usually are, elided with this shorthand. r[associated.fn.method.self-pat-mut] If the `self` parameter is prefixed with `mut`, it becomes a mutable variable, diff --git a/src/items/functions.md b/src/items/functions.md index 049eadd6d..317a59ae3 100644 --- a/src/items/functions.md +++ b/src/items/functions.md @@ -423,8 +423,8 @@ fn documented() { } ``` -> Note: Except for lints, it is idiomatic to only use outer attributes on -> function items. +> [!NOTE] +> Except for lints, it is idiomatic to only use outer attributes on function items. r[items.fn.attributes.builtin-attributes] The attributes that have meaning on a function are [`cfg`], [`cfg_attr`], [`deprecated`], diff --git a/src/items/generics.md b/src/items/generics.md index 556be79e6..2819980c6 100644 --- a/src/items/generics.md +++ b/src/items/generics.md @@ -154,8 +154,8 @@ parameter. The const expression must be a [block expression][block] (surrounded with braces) unless it is a single path segment (an [IDENTIFIER]) or a [literal] (with a possibly leading `-` token). -> **Note**: This syntactic restriction is necessary to avoid requiring -> infinite lookahead when parsing an expression inside of a type. +> [!NOTE] +> This syntactic restriction is necessary to avoid requiring infinite lookahead when parsing an expression inside of a type. ```rust fn double() { diff --git a/src/items/modules.md b/src/items/modules.md index 6ffc56d09..028b2735e 100644 --- a/src/items/modules.md +++ b/src/items/modules.md @@ -80,10 +80,8 @@ contents in a file named `mod.rs` within that directory. The above example can alternately be expressed with `crate::util`'s contents in a file named `util/mod.rs`. It is not allowed to have both `util.rs` and `util/mod.rs`. -> **Note**: Prior to `rustc` 1.30, using `mod.rs` files was the way to load -> a module with nested children. It is encouraged to use the new naming -> convention as it is more consistent, and avoids having many files named -> `mod.rs` within a project. +> [!NOTE] +> Prior to `rustc` 1.30, using `mod.rs` files was the way to load a module with nested children. It is encouraged to use the new naming convention as it is more consistent, and avoids having many files named `mod.rs` within a project. r[items.mod.outlined.path] ### The `path` attribute diff --git a/src/items/traits.md b/src/items/traits.md index 00cdd885f..85d588514 100644 --- a/src/items/traits.md +++ b/src/items/traits.md @@ -119,7 +119,8 @@ r[items.traits.dyn-compatible.associated-functions] r[items.traits.dyn-compatible.async-traits] * The [`AsyncFn`], [`AsyncFnMut`], and [`AsyncFnOnce`] traits are not dyn-compatible. -> **Note**: This concept was formerly known as *object safety*. +> [!NOTE] +> This concept was formerly known as *object safety*. ```rust # use std::rc::Rc; diff --git a/src/items/use-declarations.md b/src/items/use-declarations.md index 60ccf2272..cee55600b 100644 --- a/src/items/use-declarations.md +++ b/src/items/use-declarations.md @@ -240,9 +240,8 @@ fn main() { } ``` -> **Note**: `self` may also be used as the first segment of a path. -> The usage of `self` as the first segment and inside a `use` brace is logically the same; it means the current module of the parent segment, or the current module if there is no parent segment. -> See [`self`] in the paths chapter for more information on the meaning of a leading `self`. +> [!NOTE] +> `self` may also be used as the first segment of a path. The usage of `self` as the first segment and inside a `use` brace is logically the same; it means the current module of the parent segment, or the current module if there is no parent segment. See [`self`] in the paths chapter for more information on the meaning of a leading `self`. r[items.use.glob] ## Glob imports @@ -392,7 +391,8 @@ r[items.use.restrictions.variant] r[items.use.ambiguities] ## Ambiguities -> **Note**: This section is incomplete. +> [!NOTE] +> This section is incomplete. r[items.use.ambiguities.intro] Some situations are an error when there is an ambiguity as to which name a `use` declaration refers. This happens when there are two name candidates that do not resolve to the same entity. diff --git a/src/linkage.md b/src/linkage.md index 6d0a69761..f1076b288 100644 --- a/src/linkage.md +++ b/src/linkage.md @@ -2,8 +2,8 @@ r[link] # Linkage -> Note: This section is described more in terms of the compiler than of -> the language. +> [!NOTE] +> This section is described more in terms of the compiler than of the language. r[link.intro] The compiler supports various methods to link crates together both @@ -272,7 +272,7 @@ binary link: Passing `rlib`s directly into your foreign linker is currently unsupported. > [!NOTE] -> Rust code compiled or linked with a different instance of the Rust runtime counts as "foreign code" for the purpose of this section. +> Rust code compiled or linked with a different instance of the Rust runtime counts as "foreign code" for the purpose of this section. r[link.unwinding] ### Prohibited linkage and unwinding diff --git a/src/names/name-resolution.md b/src/names/name-resolution.md index 0f70697a6..da60d7eb3 100644 --- a/src/names/name-resolution.md +++ b/src/names/name-resolution.md @@ -1,3 +1,4 @@ # Name resolution -> **Note**: This is a placeholder for future expansion. +> [!NOTE] +> This is a placeholder for future expansion. diff --git a/src/names/preludes.md b/src/names/preludes.md index 218cb2151..3764c1725 100644 --- a/src/names/preludes.md +++ b/src/names/preludes.md @@ -36,8 +36,7 @@ Edition | `no_std` not applied | `no_std` applied 2024 | [`std::prelude::rust_2024`] | [`core::prelude::rust_2024`] -> **Note**: -> +> [!NOTE] > [`std::prelude::rust_2015`] and [`std::prelude::rust_2018`] have the same contents as [`std::prelude::v1`]. > > [`core::prelude::rust_2015`] and [`core::prelude::rust_2018`] have the same contents as [`core::prelude::v1`]. @@ -65,18 +64,15 @@ r[names.preludes.extern.edition2018] > Beginning in the 2018 edition, [use declarations] can reference crates in > the extern prelude, so it is considered unidiomatic to use `extern crate`. -> **Note**: Additional crates that ship with `rustc`, such as [`alloc`], and -> [`test`](mod@test), are not automatically included with the `--extern` flag when using -> Cargo. They must be brought into scope with an `extern crate` declaration, -> even in the 2018 edition. +> [!NOTE] +> Additional crates that ship with `rustc`, such as [`alloc`], and [`test`](mod@test), are not automatically included with the `--extern` flag when using Cargo. They must be brought into scope with an `extern crate` declaration, even in the 2018 edition. > > ```rust > extern crate alloc; > use alloc::rc::Rc; > ``` > -> Cargo does bring in `proc_macro` to the extern prelude for proc-macro crates -> only. +> Cargo does bring in `proc_macro` to the extern prelude for proc-macro crates only.