From 2a202cceebf9e49edacbbf132522937457fcbaa8 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Thu, 6 Mar 2025 09:20:04 -0800 Subject: [PATCH 1/4] Remove note about recommending using `dyn` I don't think this note is needed anymore. I think the reference should focus on documenting current rust of the latest edition, and not give too much commentary on older editions. Also, admonitions blocks don't really nest correctly. --- src/types/trait-object.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/src/types/trait-object.md b/src/types/trait-object.md index c3946252c..1ca723598 100644 --- a/src/types/trait-object.md +++ b/src/types/trait-object.md @@ -41,9 +41,6 @@ For example, given a trait `Trait`, the following are all trait objects: r[type.trait-object.syntax-edition2021] > **Edition differences**: Before the 2021 edition, the `dyn` keyword may be > omitted. -> -> Note: For clarity, it is recommended to always use the `dyn` keyword on your -> trait objects unless your codebase supports compiling with Rust 1.26 or lower. r[type.trait-object.syntax-edition2015] > **Edition differences**: In the 2015 edition, if the first bound of the From 484d3f2ce43de2d20b24c817c1a29831df70e01e Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Thu, 6 Mar 2025 09:21:49 -0800 Subject: [PATCH 2/4] Switch all note blocks to use admonition syntax This will allow us to maintain consistency, and apply styling. --- src/attributes.md | 3 ++- src/attributes/codegen.md | 21 ++++++++++------ src/attributes/debugger.md | 3 ++- src/attributes/diagnostics.md | 21 ++++++++++------ src/attributes/limits.md | 9 ++++--- src/attributes/testing.md | 6 +++-- src/behavior-considered-undefined.md | 6 +++-- src/comments.md | 6 +++-- src/conditional-compilation.md | 12 ++++++---- src/crates-and-source-files.md | 9 ++++--- src/destructors.md | 9 +++---- src/dynamically-sized-types.md | 5 ++-- src/expressions.md | 12 ++++++---- src/expressions/block-expr.md | 9 ++++--- src/expressions/call-expr.md | 3 ++- src/expressions/field-expr.md | 3 ++- src/expressions/literal-expr.md | 36 ++++++++++++++++++---------- src/expressions/loop-expr.md | 3 ++- src/expressions/match-expr.md | 6 +++-- src/expressions/method-call-expr.md | 3 ++- src/expressions/operator-expr.md | 9 ++++--- src/expressions/tuple-expr.md | 6 +++-- src/identifiers.md | 3 ++- src/inline-assembly.md | 12 ++++++---- src/input-format.md | 3 ++- src/introduction.md | 5 ++-- src/items/associated-items.md | 3 ++- src/items/functions.md | 3 ++- src/items/generics.md | 3 ++- src/items/modules.md | 3 ++- src/items/traits.md | 3 ++- src/items/use-declarations.md | 6 +++-- src/linkage.md | 3 ++- src/names/name-resolution.md | 3 ++- src/names/preludes.md | 9 +++---- src/procedural-macros.md | 3 ++- src/tokens.md | 6 +++-- src/type-coercions.md | 3 ++- src/type-layout.md | 33 ++++++++++++++++--------- src/types/array.md | 3 ++- src/types/boolean.md | 6 +++-- src/types/closure.md | 3 ++- src/types/impl-trait.md | 8 ++++--- src/types/numeric.md | 3 ++- src/visibility-and-privacy.md | 3 ++- 45 files changed, 216 insertions(+), 114 deletions(-) diff --git a/src/attributes.md b/src/attributes.md index 6d286c60d..35c2636cd 100644 --- a/src/attributes.md +++ b/src/attributes.md @@ -227,7 +227,8 @@ struct S { pub fn f() {} ``` -> Note: `rustc` currently recognizes the tools "clippy", "rustfmt", "diagnostic", +> [!NOTE] +> `rustc` currently recognizes the tools "clippy", "rustfmt", "diagnostic", > "miri" and "rust_analyzer". r[attributes.builtin] diff --git a/src/attributes/codegen.md b/src/attributes/codegen.md index c309cd2a1..84ef6de0b 100644 --- a/src/attributes/codegen.md +++ b/src/attributes/codegen.md @@ -26,7 +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 +> [!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. @@ -39,7 +40,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* +> [!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] @@ -229,7 +231,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 +> [!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,7 +393,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. +> [!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. @@ -427,10 +431,12 @@ fn f() { } ``` -> Note: `core` provides [`core::panic::Location::caller`] for observing caller locations. It wraps +> [!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 +> [!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,7 +510,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 +> [!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 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..dcbd059a7 100644 --- a/src/attributes/diagnostics.md +++ b/src/attributes/diagnostics.md @@ -37,7 +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`, +> [!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 @@ -98,7 +99,8 @@ pub mod m3 { } ``` -> Note: `rustc` allows setting lint levels on the +> [!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. @@ -222,7 +224,8 @@ pub fn another_example() { } ``` -> Note: The behavior of `#[expect(unfulfilled_lint_expectations)]` is currently +> [!NOTE] +> The behavior of `#[expect(unfulfilled_lint_expectations)]` is currently > defined to always generate the `unfulfilled_lint_expectations` lint. r[attributes.diagnostics.lint.group] @@ -297,7 +300,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,7 +437,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 +> [!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. @@ -452,7 +457,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 `_` +> [!NOTE] +> It is idiomatic to use a [let statement] with a pattern of `_` > when a must-used value is purposely discarded. > > ```rust @@ -558,7 +564,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..f229f1436 100644 --- a/src/attributes/testing.md +++ b/src/attributes/testing.md @@ -26,7 +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` +> [!NOTE] +> The test mode is enabled by passing the `--test` argument to `rustc` > or using `cargo test`. r[attributes.testing.test.success] @@ -69,7 +70,8 @@ fn mytest() { } ``` -> **Note**: The `rustc` test harness supports the `--include-ignored` flag to +> [!NOTE] +> The `rustc` test harness supports the `--include-ignored` flag to > force ignored tests to be run. r[attributes.testing.should_panic] diff --git a/src/behavior-considered-undefined.md b/src/behavior-considered-undefined.md index a11e67aec..f3952cb8c 100644 --- a/src/behavior-considered-undefined.md +++ b/src/behavior-considered-undefined.md @@ -101,7 +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 +> [!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 @@ -237,7 +238,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 + > [!NOTE] + > `rustc` achieves this with the unstable > `rustc_layout_scalar_valid_range_*` attributes. r[undefined.validity.undef] diff --git a/src/comments.md b/src/comments.md index 6b4a954e4..320885da5 100644 --- a/src/comments.md +++ b/src/comments.md @@ -71,13 +71,15 @@ 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 +> [!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..7340204bf 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,10 +81,12 @@ 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 +> [!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 +> [!NOTE] +> Configuration options with the key `feature` are a convention used > by [Cargo][cargo-feature] for specifying compile-time options and optional > dependencies. @@ -422,7 +425,8 @@ fn bewitched() {} fn bewitched() {} ``` -> **Note**: The `cfg_attr` can expand to another `cfg_attr`. For example, +> [!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)]`. diff --git a/src/crates-and-source-files.md b/src/crates-and-source-files.md index 64bff1616..e56b55f54 100644 --- a/src/crates-and-source-files.md +++ b/src/crates-and-source-files.md @@ -7,7 +7,8 @@ r[crate.syntax] >    [_InnerAttribute_]\*\ >    [_Item_]\* -> Note: Although Rust, like any other language, can be implemented by an +> [!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. @@ -60,7 +61,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 +113,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..cdbcca5ba 100644 --- a/src/destructors.md +++ b/src/destructors.md @@ -211,8 +211,7 @@ 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**: -> +> [!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 @@ -315,7 +314,8 @@ r[destructors.scope.lifetime-extension] ### Temporary lifetime extension -> **Note**: The exact rules for temporary lifetime extension are subject to +> [!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] @@ -432,7 +432,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`. +> [!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] diff --git a/src/dynamically-sized-types.md b/src/dynamically-sized-types.md index e65d3e022..a398fb3ac 100644 --- a/src/dynamically-sized-types.md +++ b/src/dynamically-sized-types.md @@ -34,13 +34,14 @@ 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 +> [!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..eaf662662 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,7 +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 +> [!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 +144,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 +181,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..4ad323989 100644 --- a/src/expressions/block-expr.md +++ b/src/expressions/block-expr.md @@ -59,12 +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. +> [!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 @@ -110,7 +112,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..aec202d1e 100644 --- a/src/expressions/call-expr.md +++ b/src/expressions/call-expr.md @@ -44,7 +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. +> [!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. 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..2280f71f6 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,7 +104,8 @@ 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. +> [!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"; @@ -150,7 +154,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 +243,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 +289,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 +336,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,10 +431,12 @@ 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. +> [!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. +> [!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] @@ -475,9 +485,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. +> [!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. diff --git a/src/expressions/loop-expr.md b/src/expressions/loop-expr.md index c60453143..73923c51b 100644 --- a/src/expressions/loop-expr.md +++ b/src/expressions/loop-expr.md @@ -218,7 +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. +> [!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] diff --git a/src/expressions/match-expr.md b/src/expressions/match-expr.md index 9c7fecf44..89b11d76d 100644 --- a/src/expressions/match-expr.md +++ b/src/expressions/match-expr.md @@ -91,7 +91,8 @@ match S(1, 2) { } ``` -> Note: The `2..=9` is a [Range Pattern], not a [Range Expression]. +> [!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] @@ -127,7 +128,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. +> [!NOTE] +> Multiple matches using the `|` operator can cause the pattern guard and the side effects it has to execute multiple times. > For example: > > ```rust diff --git a/src/expressions/method-call-expr.md b/src/expressions/method-call-expr.md index f6e748328..4e82349fd 100644 --- a/src/expressions/method-call-expr.md +++ b/src/expressions/method-call-expr.md @@ -40,7 +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. +> [!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 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..7a968e01b 100644 --- a/src/items/functions.md +++ b/src/items/functions.md @@ -423,7 +423,8 @@ fn documented() { } ``` -> Note: Except for lints, it is idiomatic to only use outer attributes on +> [!NOTE] +> Except for lints, it is idiomatic to only use outer attributes on > function items. r[items.fn.attributes.builtin-attributes] diff --git a/src/items/generics.md b/src/items/generics.md index 556be79e6..2b7325109 100644 --- a/src/items/generics.md +++ b/src/items/generics.md @@ -154,7 +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 +> [!NOTE] +> This syntactic restriction is necessary to avoid requiring > infinite lookahead when parsing an expression inside of a type. ```rust diff --git a/src/items/modules.md b/src/items/modules.md index 6ffc56d09..822c0317a 100644 --- a/src/items/modules.md +++ b/src/items/modules.md @@ -80,7 +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 +> [!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. 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..a1adccd79 100644 --- a/src/items/use-declarations.md +++ b/src/items/use-declarations.md @@ -240,7 +240,8 @@ fn main() { } ``` -> **Note**: `self` may also be used as the first segment of a path. +> [!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`. @@ -392,7 +393,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..6c4306b40 100644 --- a/src/linkage.md +++ b/src/linkage.md @@ -2,7 +2,8 @@ r[link] # Linkage -> Note: This section is described more in terms of the compiler than of +> [!NOTE] +> This section is described more in terms of the compiler than of > the language. r[link.intro] 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..504ea595a 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,7 +64,8 @@ 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 +> [!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. @@ -107,7 +107,8 @@ r[names.preludes.extern.no_std.core] * Injects the [`core`] crate into the crate root instead of [`std`], and pulls in all macros exported from `core` in the [`macro_use` prelude]. -> **Note**: Using the core prelude over the standard prelude is useful when +> [!NOTE] +> Using the core prelude over the standard prelude is useful when > either the crate is targeting a platform that does not support the standard > library or is purposefully not using the capabilities of the standard > library. Those capabilities are mainly dynamic memory allocation (e.g. `Box` diff --git a/src/procedural-macros.md b/src/procedural-macros.md index d717d9a50..c5d198de9 100644 --- a/src/procedural-macros.md +++ b/src/procedural-macros.md @@ -18,7 +18,8 @@ Procedural macros must be defined in the root of a crate with the [crate type] o `proc-macro`. The macros may not be used from the crate where they are defined, and can only be used when imported in another crate. -> **Note**: When using Cargo, Procedural macro crates are defined with the +> [!NOTE] +> When using Cargo, Procedural macro crates are defined with the > `proc-macro` key in your manifest: > > ```toml diff --git a/src/tokens.md b/src/tokens.md index 317a437ce..c08e3bbd7 100644 --- a/src/tokens.md +++ b/src/tokens.md @@ -40,7 +40,8 @@ Literals are tokens used in [literal expressions]. [^nsets]: The number of `#`s on each side of the same literal must be equivalent. -> **Note**: Character and string literal tokens never include the sequence of `U+000D` (CR) immediately followed by `U+000A` (LF): this pair would have been previously transformed into a single `U+000A` (LF). +> [!NOTE] +> Character and string literal tokens never include the sequence of `U+000D` (CR) immediately followed by `U+000A` (LF): this pair would have been previously transformed into a single `U+000A` (LF). #### ASCII escapes @@ -624,7 +625,8 @@ let cat = example.01; // ERROR no field named `01` let horse = example.0b10; // ERROR no field named `0b10` ``` -> **Note**: Tuple indices may include certain suffixes, but this is not intended to be valid, and may be removed in a future version. +> [!NOTE] +> Tuple indices may include certain suffixes, but this is not intended to be valid, and may be removed in a future version. > See for more information. r[lex.token.literal.float] diff --git a/src/type-coercions.md b/src/type-coercions.md index 1f0166a6d..49b8bab02 100644 --- a/src/type-coercions.md +++ b/src/type-coercions.md @@ -225,7 +225,8 @@ Additionally, a type `Foo` can implement `CoerceUnsized>` when `T` implements `Unsize` or `CoerceUnsized>`. This allows it to provide an unsized coercion to `Foo`. -> Note: While the definition of the unsized coercions and their implementation +> [!NOTE] +> While the definition of the unsized coercions and their implementation > has been stabilized, the traits themselves are not yet stable and therefore > can't be used directly in stable Rust. diff --git a/src/type-layout.md b/src/type-layout.md index 316075ac0..32a3292d0 100644 --- a/src/type-layout.md +++ b/src/type-layout.md @@ -88,7 +88,8 @@ r[layout.pointer.unsized] Pointers to unsized types are sized. The size and alignment is guaranteed to be at least equal to the size and alignment of a pointer. -> Note: Though you should not rely on this, all pointers to +> [!NOTE] +> Though you should not rely on this, all pointers to > DSTs are currently twice the > size of the size of `usize` and have the same alignment. @@ -106,7 +107,8 @@ r[layout.slice] Slices have the same layout as the section of the array they slice. -> Note: This is about the raw `[T]` type, not pointers (`&[T]`, `Box<[T]>`, +> [!NOTE] +> This is about the raw `[T]` type, not pointers (`&[T]`, `Box<[T]>`, > etc.) to slices. r[layout.str] @@ -131,7 +133,8 @@ r[layout.trait-object] Trait objects have the same layout as the value the trait object is of. -> Note: This is about the raw trait object types, not pointers (`&dyn Trait`, +> [!NOTE] +> This is about the raw trait object types, not pointers (`&dyn Trait`, > `Box`, etc.) to trait objects. r[layout.closure] @@ -191,7 +194,8 @@ struct AlignedStruct { } ``` -> Note: As a consequence of the representation being an attribute on the item, +> [!NOTE] +> As a consequence of the representation being an attribute on the item, > the representation does not depend on generic parameters. Any two types with > the same name have the same representation. For example, `Foo` and > `Foo` both have the same representation. @@ -312,7 +316,8 @@ struct.size = current_offset + padding_needed_for(current_offset, struct.alignme > [!WARNING] > This pseudocode uses a naive algorithm that ignores overflow issues for the sake of clarity. To perform memory layout computations in actual code, use [`Layout`]. -> Note: This algorithm can produce zero-sized structs. In C, an empty struct +> [!NOTE] +> This algorithm can produce zero-sized structs. In C, an empty struct > declaration like `struct Foo { }` is illegal. However, both gcc and clang > support options to enable such structs, and assign them size zero. C++, in > contrast, gives empty structs a size of 1, unless they are inherited from or @@ -360,7 +365,8 @@ r[layout.repr.c.enum] For [field-less enums], the `C` representation has the size and alignment of the default `enum` size and alignment for the target platform's C ABI. -> Note: The enum representation in C is implementation defined, so this is +> [!NOTE] +> The enum representation in C is implementation defined, so this is > really a "best guess". In particular, this may be incorrect when the C code > of interest is compiled with certain flags. @@ -381,7 +387,8 @@ r[layout.repr.c.adt.fields] - a `repr(C)` union of `repr(C)` structs for the fields of each variant that had them ("the payload") -> Note: Due to the representation of `repr(C)` structs and unions, if a variant +> [!NOTE] +> Due to the representation of `repr(C)` structs and unions, if a variant > has a single field there is no difference between putting that field directly > in the union or wrapping it in a struct; any system which wishes to manipulate > such an `enum`'s representation may therefore use whichever form is more @@ -436,7 +443,8 @@ struct MyCFields { x: u32, y: u8 } struct MyDFields; ``` -> Note: `union`s with non-`Copy` fields are unstable, see [55149]. +> [!NOTE] +> `union`s with non-`Copy` fields are unstable, see [55149]. r[layout.repr.primitive] ### Primitive representations @@ -470,7 +478,8 @@ The representation of a primitive representation enum is a `repr(C)` union of in the union is the primitive representation version of the enum with all fields removed ("the tag") and the remaining fields are the fields of that variant. -> Note: This representation is unchanged if the tag is given its own member in +> [!NOTE] +> This representation is unchanged if the tag is given its own member in > the union, should that make manipulation more clear for you (although to > follow the C++ standard the tag member should be wrapped in a `struct`). @@ -515,7 +524,8 @@ struct MyVariantC { tag: MyEnumDiscriminant, x: u32, y: u8 } struct MyVariantD(MyEnumDiscriminant); ``` -> Note: `union`s with non-`Copy` fields are unstable, see [55149]. +> [!NOTE] +> `union`s with non-`Copy` fields are unstable, see [55149]. r[layout.repr.primitive-c] #### Combining primitive representations of enums with fields and `#[repr(C)]` @@ -630,7 +640,8 @@ The `align` modifier can also be applied on an `enum`. When it is, the effect on the `enum`'s alignment is the same as if the `enum` was wrapped in a newtype `struct` with the same `align` modifier. -> Note: References to unaligned fields are not allowed because it is [undefined behavior]. +> [!NOTE] +> References to unaligned fields are not allowed because it is [undefined behavior]. > When fields are unaligned due to an alignment modifier, consider the following options for using references and dereferences: > > ```rust diff --git a/src/types/array.md b/src/types/array.md index d18ffa212..27e6d9dd4 100644 --- a/src/types/array.md +++ b/src/types/array.md @@ -27,7 +27,8 @@ r[type.array.index] All elements of arrays are always initialized, and access to an array is always bounds-checked in safe methods and operators. -> Note: The [`Vec`] standard library type provides a heap-allocated resizable +> [!NOTE] +> The [`Vec`] standard library type provides a heap-allocated resizable > array type. [_Expression_]: ../expressions.md diff --git a/src/types/boolean.md b/src/types/boolean.md index 83c4b8193..e1611a4b3 100644 --- a/src/types/boolean.md +++ b/src/types/boolean.md @@ -33,7 +33,8 @@ r[type.bool.usage-condition] r[type.bool.usage-lazy-operator] * The operands in [lazy boolean operator expressions][lazy] -> **Note**: The boolean type acts similarly to but is not an [enumerated type]. +> [!NOTE] +> The boolean type acts similarly to but is not an [enumerated type]. In practice, this mostly means that constructors are not associated to the type (e.g. `bool::true`). @@ -42,7 +43,8 @@ Like all primitives, the boolean type [implements][p-impl] the [traits][p-traits] [`Clone`][p-clone], [`Copy`][p-copy], [`Sized`][p-sized], [`Send`][p-send], and [`Sync`][p-sync]. -> **Note**: See the [standard library docs](bool) for library operations. +> [!NOTE] +> See the [standard library docs](bool) for library operations. r[type.bool.expr] ## Operations on boolean values diff --git a/src/types/closure.md b/src/types/closure.md index f9719d00b..3982f74e1 100644 --- a/src/types/closure.md +++ b/src/types/closure.md @@ -484,7 +484,8 @@ r[type.closure.call.fn] * A closure which does not mutate or move out of any captured variables implements [`Fn`], indicating that it can be called by shared reference. -> Note: `move` closures may still implement [`Fn`] or [`FnMut`], even though +> [!NOTE] +> `move` closures may still implement [`Fn`] or [`FnMut`], even though > they capture variables by move. This is because the traits implemented by a > closure type are determined by what the closure does with captured values, > not how it captures them. diff --git a/src/types/impl-trait.md b/src/types/impl-trait.md index bc873eb5d..479959d0e 100644 --- a/src/types/impl-trait.md +++ b/src/types/impl-trait.md @@ -27,7 +27,8 @@ fn bar() -> impl Trait { r[type.impl-trait.param] ## Anonymous type parameters -> Note: This is often called "impl Trait in argument position". +> [!NOTE] +> This is often called "impl Trait in argument position". (The term "parameter" is more correct here, but "impl Trait in argument position" is the phrasing used during the development of this feature, and it remains in parts of the implementation.) r[type.impl-trait.param.intro] @@ -51,7 +52,7 @@ fn with_impl_trait(arg: impl Trait) { r[type.impl-trait.param.generic] That is, `impl Trait` in argument position is syntactic sugar for a generic type parameter like ``, except that the type is anonymous and doesn't appear in the [_GenericParams_] list. -> **Note:** +> [!NOTE] > For function parameters, generic type parameters and `impl Trait` are not exactly equivalent. > With a generic parameter such as ``, the caller has the option to explicitly specify the generic argument for `T` at the call site using [_GenericArgs_], for example, `foo::(1)`. > Changing a parameter from either one to the other can constitute a breaking change for the callers of a function, since this changes the number of generic arguments. @@ -59,7 +60,8 @@ That is, `impl Trait` in argument position is syntactic sugar for a generic type r[type.impl-trait.return] ## Abstract return types -> Note: This is often called "impl Trait in return position". +> [!NOTE] +> This is often called "impl Trait in return position". r[type.impl-trait.return.intro] Functions can use `impl Trait` to return an abstract return type. diff --git a/src/types/numeric.md b/src/types/numeric.md index b4db2121f..1091cae28 100644 --- a/src/types/numeric.md +++ b/src/types/numeric.md @@ -50,7 +50,8 @@ within an object along with one byte past the end. r[type.numeric.int.size.minimum] `usize` and `isize` are at least 16-bits wide. -> **Note**: Many pieces of Rust code may assume that pointers, `usize`, and +> [!NOTE] +> Many pieces of Rust code may assume that pointers, `usize`, and > `isize` are either 32-bit or 64-bit. As a consequence, 16-bit > pointer support is limited and may require explicit care and acknowledgment > from a library to support. diff --git a/src/visibility-and-privacy.md b/src/visibility-and-privacy.md index 3d9f499ad..711723819 100644 --- a/src/visibility-and-privacy.md +++ b/src/visibility-and-privacy.md @@ -232,7 +232,8 @@ fn bar() { fn main() { bar() } ``` -> **Note:** This syntax only adds another restriction to the visibility of an +> [!NOTE] +> This syntax only adds another restriction to the visibility of an > item. It does not guarantee that the item is visible within all parts of the > specified scope. To access an item, all of its parent items up to the > current scope must still be visible as well. From f5cffea9b90ecb3a48e617acf07f426f5dcd9289 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Thu, 6 Mar 2025 09:36:05 -0800 Subject: [PATCH 3/4] Unwrap all note blocks This is to follow the style guide (and fix some broken blockquotes). --- src/attributes.md | 3 +-- src/attributes/codegen.md | 28 +++++--------------- src/attributes/diagnostics.md | 18 ++++--------- src/attributes/testing.md | 6 ++--- src/behavior-considered-undefined.md | 9 ++----- src/comments.md | 6 +---- src/conditional-compilation.md | 12 +++------ src/crates-and-source-files.md | 5 +--- src/destructors.md | 11 +++----- src/dynamically-sized-types.md | 3 +-- src/expressions.md | 3 +-- src/expressions/block-expr.md | 3 +-- src/expressions/call-expr.md | 4 +-- src/expressions/literal-expr.md | 19 +++++--------- src/expressions/loop-expr.md | 3 +-- src/expressions/match-expr.md | 6 ++--- src/expressions/method-call-expr.md | 3 +-- src/items/functions.md | 3 +-- src/items/generics.md | 3 +-- src/items/modules.md | 5 +--- src/items/use-declarations.md | 4 +-- src/linkage.md | 5 ++-- src/names/preludes.md | 14 +++------- src/panic.md | 2 +- src/procedural-macros.md | 3 +-- src/tokens.md | 3 +-- src/type-coercions.md | 4 +-- src/type-layout.md | 39 +++++++--------------------- src/types/array.md | 3 +-- src/types/boolean.md | 4 +-- src/types/closure.md | 5 +--- src/types/impl-trait.md | 7 ++--- src/types/numeric.md | 5 +--- src/visibility-and-privacy.md | 5 +--- 34 files changed, 68 insertions(+), 188 deletions(-) diff --git a/src/attributes.md b/src/attributes.md index 35c2636cd..d81e50ced 100644 --- a/src/attributes.md +++ b/src/attributes.md @@ -228,8 +228,7 @@ pub fn f() {} ``` > [!NOTE] -> `rustc` currently recognizes the tools "clippy", "rustfmt", "diagnostic", -> "miri" and "rust_analyzer". +> `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 84ef6de0b..aa5e70617 100644 --- a/src/attributes/codegen.md +++ b/src/attributes/codegen.md @@ -27,9 +27,7 @@ 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. +> 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: @@ -41,8 +39,7 @@ There are three ways to use the inline attribute: 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. +> `#[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 @@ -232,8 +229,7 @@ Reference Manual], or elsewhere on [developer.arm.com]. [developer.arm.com]: https://developer.arm.com > [!NOTE] -> The following pairs of features should both be marked as enabled -> or disabled together if used: +> 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. @@ -394,10 +390,7 @@ 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. +> `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 @@ -432,12 +425,10 @@ fn f() { ``` > [!NOTE] -> `core` provides [`core::panic::Location::caller`] for observing caller locations. It wraps -> the [`core::intrinsics::caller_location`] intrinsic implemented by `rustc`. +> `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. +> Because the resulting `Location` is a hint, an implementation may halt its walk up the stack early. See [Limitations](#limitations) for important caveats. #### Examples @@ -511,12 +502,7 @@ caller information across virtual calls. A common example of this coercion is th 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. +> 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/diagnostics.md b/src/attributes/diagnostics.md index dcbd059a7..e03971b4c 100644 --- a/src/attributes/diagnostics.md +++ b/src/attributes/diagnostics.md @@ -38,8 +38,7 @@ r[attributes.diagnostics.lint.forbid] 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]. +> 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 { @@ -100,9 +99,7 @@ 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. +> `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 @@ -225,8 +222,7 @@ pub fn another_example() { ``` > [!NOTE] -> The behavior of `#[expect(unfulfilled_lint_expectations)]` is currently -> defined to always generate the `unfulfilled_lint_expectations` lint. +> 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 @@ -438,10 +434,7 @@ 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. +> 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] @@ -458,8 +451,7 @@ 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. +> It is idiomatic to use a [let statement] with a pattern of `_` when a must-used value is purposely discarded. > > ```rust > #[must_use] diff --git a/src/attributes/testing.md b/src/attributes/testing.md index f229f1436..a11a6b371 100644 --- a/src/attributes/testing.md +++ b/src/attributes/testing.md @@ -27,8 +27,7 @@ Test functions must be free, monomorphic functions that take no arguments, and t onwards, also update it in the crates-and-source-files.md file --> > [!NOTE] -> The test mode is enabled by passing the `--test` argument to `rustc` -> or using `cargo test`. +> 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. @@ -71,8 +70,7 @@ fn mytest() { ``` > [!NOTE] -> The `rustc` test harness supports the `--include-ignored` flag to -> force ignored tests to be run. +> 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 f3952cb8c..d2a7d72fc 100644 --- a/src/behavior-considered-undefined.md +++ b/src/behavior-considered-undefined.md @@ -102,11 +102,7 @@ r[undefined.runtime] * 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. +> 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 @@ -239,8 +235,7 @@ r[undefined.validity.valid-range] In the standard library, this affects [`NonNull`] and [`NonZero`]. > [!NOTE] - > `rustc` achieves this with the unstable - > `rustc_layout_scalar_valid_range_*` attributes. + > `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 320885da5..d66b6eb23 100644 --- a/src/comments.md +++ b/src/comments.md @@ -72,11 +72,7 @@ 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. +> 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). diff --git a/src/conditional-compilation.md b/src/conditional-compilation.md index 7340204bf..a214326e2 100644 --- a/src/conditional-compilation.md +++ b/src/conditional-compilation.md @@ -82,13 +82,10 @@ 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`. +> 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. +> 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` @@ -426,10 +423,7 @@ 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)]`. +> 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 e56b55f54..1ba86d63e 100644 --- a/src/crates-and-source-files.md +++ b/src/crates-and-source-files.md @@ -8,10 +8,7 @@ r[crate.syntax] >    [_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. +> 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 diff --git a/src/destructors.md b/src/destructors.md index cdbcca5ba..5467c5abb 100644 --- a/src/destructors.md +++ b/src/destructors.md @@ -212,10 +212,7 @@ smallest scope that contains the expression and is one of the following: * The entirety of the tail expression of a block ([destructors.scope.temporary.edition2024]). > [!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. +> 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 +312,7 @@ r[destructors.scope.lifetime-extension] > [!NOTE] -> The exact rules for temporary lifetime extension are subject to -> change. This is describing the current behavior only. +> 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 @@ -433,8 +429,7 @@ 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. +> 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 a398fb3ac..b30958ded 100644 --- a/src/dynamically-sized-types.md +++ b/src/dynamically-sized-types.md @@ -35,8 +35,7 @@ r[dynamic-sized.struct-field] DST. > [!NOTE] -> [Variables], function parameters, [const] items, and [static] items must be -`Sized`. +> [Variables], function parameters, [const] items, and [static] items must be `Sized`. [sized]: special-types-and-traits.md#sized [Slices]: types/slice.md diff --git a/src/expressions.md b/src/expressions.md index eaf662662..8827c9592 100644 --- a/src/expressions.md +++ b/src/expressions.md @@ -128,8 +128,7 @@ The operands of these expressions are evaluated prior to applying the effects of 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. +> 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: diff --git a/src/expressions/block-expr.md b/src/expressions/block-expr.md index 4ad323989..3d6936bc8 100644 --- a/src/expressions/block-expr.md +++ b/src/expressions/block-expr.md @@ -66,8 +66,7 @@ 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. +> 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; diff --git a/src/expressions/call-expr.md b/src/expressions/call-expr.md index aec202d1e..9f3f6bf76 100644 --- a/src/expressions/call-expr.md +++ b/src/expressions/call-expr.md @@ -45,9 +45,7 @@ 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. +> 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/literal-expr.md b/src/expressions/literal-expr.md index 2280f71f6..78cc959fe 100644 --- a/src/expressions/literal-expr.md +++ b/src/expressions/literal-expr.md @@ -105,8 +105,8 @@ 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: +> 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\ @@ -119,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 @@ -432,12 +429,10 @@ 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. +> 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. +> `-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 @@ -489,9 +484,7 @@ r[expr.literal.float.value] > `-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. +> `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 73923c51b..c3e3c1529 100644 --- a/src/expressions/loop-expr.md +++ b/src/expressions/loop-expr.md @@ -219,8 +219,7 @@ 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] -> 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. +> 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 89b11d76d..9071d7bef 100644 --- a/src/expressions/match-expr.md +++ b/src/expressions/match-expr.md @@ -92,8 +92,7 @@ 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. +> 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. @@ -129,8 +128,7 @@ 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: +> 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 4e82349fd..f35e9210a 100644 --- a/src/expressions/method-call-expr.md +++ b/src/expressions/method-call-expr.md @@ -41,8 +41,7 @@ Then, for each candidate type `T`, search for a [visible] method with a receiver 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. +> 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/items/functions.md b/src/items/functions.md index 7a968e01b..317a59ae3 100644 --- a/src/items/functions.md +++ b/src/items/functions.md @@ -424,8 +424,7 @@ fn documented() { ``` > [!NOTE] -> Except for lints, it is idiomatic to only use outer attributes on -> function items. +> 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 2b7325109..2819980c6 100644 --- a/src/items/generics.md +++ b/src/items/generics.md @@ -155,8 +155,7 @@ parameter. The const expression must be a [block expression][block] 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. +> 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 822c0317a..028b2735e 100644 --- a/src/items/modules.md +++ b/src/items/modules.md @@ -81,10 +81,7 @@ 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. +> 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/use-declarations.md b/src/items/use-declarations.md index a1adccd79..cee55600b 100644 --- a/src/items/use-declarations.md +++ b/src/items/use-declarations.md @@ -241,9 +241,7 @@ 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`. +> `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 diff --git a/src/linkage.md b/src/linkage.md index 6c4306b40..f1076b288 100644 --- a/src/linkage.md +++ b/src/linkage.md @@ -3,8 +3,7 @@ r[link] > [!NOTE] -> This section is described more in terms of the compiler than of -> the language. +> 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 @@ -273,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/preludes.md b/src/names/preludes.md index 504ea595a..3764c1725 100644 --- a/src/names/preludes.md +++ b/src/names/preludes.md @@ -65,18 +65,14 @@ r[names.preludes.extern.edition2018] > 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. +> 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.