From 414edffbf3c4d4af9f9375a6092a96ecc434b4d2 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Thu, 15 Jan 2026 09:39:54 -0800 Subject: [PATCH] Rename the ".general" rules The "general" suffix seemed too generic to me, and also didn't quite fit with some of the style in the rest of the grammar. Some of these are difficult to come up with good names for, and I'm not entirely happy with this. My thinking is: - `.intro` is for informative introductions to a section. My intention is that every normative rule is testable. However, many of these `.intro` rules define terms, and I think those should possibly be normative (like [ISO/IEC Directives](https://www.iso.org/sites/directives/current/part2/index.xhtml#_idTextAnchor212)). I would like to rethink how `.intro` works. I appreciate having introductions that are more generalized, but it is often very difficult to introduce a section without defining some terms first. I would also like to come up with a better strategy of "this is a testable rule" versus "this rule defines a term, but that by isn't testable". - Switched some of these to be more specific words tailored to their context. - Used `.def` for some of these that *define* a thing. `.def` is used in a variety of other places. We have not standardized on it, and I'm not sure it is working in a way that is clear (is it defining a term? behavior? rule? general principle?). I think this is being used in ways that are inconsistent, and would like to figure out something better. --- src/behavior-considered-undefined.md | 8 ++++---- src/conditional-compilation.md | 24 ++++++++++++------------ src/const_eval.md | 6 +++--- src/crates-and-source-files.md | 2 +- src/items/implementations.md | 2 +- src/type-layout.md | 2 +- 6 files changed, 22 insertions(+), 22 deletions(-) diff --git a/src/behavior-considered-undefined.md b/src/behavior-considered-undefined.md index 4dc2910e85..9ecf5b2253 100644 --- a/src/behavior-considered-undefined.md +++ b/src/behavior-considered-undefined.md @@ -1,7 +1,7 @@ r[undefined] # Behavior considered undefined -r[undefined.general] +r[undefined.intro] Rust code is incorrect if it exhibits any of the behaviors in the following list. This includes code within `unsafe` blocks and `unsafe` functions. `unsafe` only means that avoiding undefined behavior is on the programmer; it @@ -93,7 +93,7 @@ r[undefined.misaligned] ## Places based on misaligned pointers [based on a misaligned pointer]: #places-based-on-misaligned-pointers -r[undefined.misaligned.general] +r[undefined.misaligned.ptr] A place is said to be "based on a misaligned pointer" if the last `*` projection during place computation was performed on a pointer that was not aligned for its type. (If there is no `*` projection in the place expression, then this is @@ -133,7 +133,7 @@ r[undefined.dangling] ## Dangling pointers [dangling]: #dangling-pointers -r[undefined.dangling.general] +r[undefined.dangling.def] A reference/pointer is "dangling" if not all of the bytes it [points to] are part of the same live allocation (so in particular they all have to be part of *some* allocation). @@ -155,7 +155,7 @@ r[undefined.validity] ## Invalid values [invalid-values]: #invalid-values -r[undefined.validity.general] +r[undefined.validity.def] The Rust compiler assumes that all values produced during program execution are "valid", and producing an invalid value is hence immediate UB. diff --git a/src/conditional-compilation.md b/src/conditional-compilation.md index f03362063c..f770813fe0 100644 --- a/src/conditional-compilation.md +++ b/src/conditional-compilation.md @@ -27,7 +27,7 @@ ConfigurationPredicateList -> ConfigurationPredicate (`,` ConfigurationPredicate)* `,`? ``` -r[cfg.general] +r[cfg.intro] *Conditionally compiled source code* is source code that is compiled only under certain conditions. r[cfg.attributes-macro] @@ -73,7 +73,7 @@ Keys do not need to be unique. For example, both `feature = "std"` and `feature r[cfg.options.set] ## Set configuration options -r[cfg.options.general] +r[cfg.options.intro] Which configuration options are set is determined statically during the compilation of the crate. @@ -96,7 +96,7 @@ configuration option from within the source code of the crate being compiled. r[cfg.target_arch] ### `target_arch` -r[cfg.target_arch.gen] +r[cfg.target_arch.def] Key-value option set once with the target's CPU architecture. The value is similar to the first element of the platform's target triple, but not identical. @@ -115,7 +115,7 @@ Example values: r[cfg.target_feature] ### `target_feature` -r[cfg.target_feature.general] +r[cfg.target_feature.def] Key-value option set for each platform feature available for the current compilation target. @@ -140,7 +140,7 @@ An additional feature of `crt-static` is available to the r[cfg.target_os] ### `target_os` -r[cfg.target_os.general] +r[cfg.target_os.def] Key-value option set once with the target's operating system. This value is similar to the second and third element of the platform's target triple. @@ -161,7 +161,7 @@ Example values: r[cfg.target_family] ### `target_family` -r[cfg.target_family.general] +r[cfg.target_family.def] Key-value option providing a more generic description of a target, such as the family of the operating systems or architectures that the target generally falls into. Any number of `target_family` key-value pairs can be set. @@ -185,7 +185,7 @@ r[cfg.target_family.windows] r[cfg.target_env] ### `target_env` -r[cfg.target_env.general] +r[cfg.target_env.def] Key-value option set with further disambiguating information about the target platform with information about the ABI or `libc` used. For historical reasons, this value is only defined as not the empty-string when actually needed for @@ -208,7 +208,7 @@ Example values: r[cfg.target_abi] ### `target_abi` -r[cfg.target_abi.general] +r[cfg.target_abi.def] Key-value option set to further disambiguate the target with information about the target ABI. @@ -234,7 +234,7 @@ on the endianness of the target's CPU. r[cfg.target_pointer_width] ### `target_pointer_width` -r[cfg.target_pointer_width.general] +r[cfg.target_pointer_width.def] Key-value option set once with the target's pointer width in bits. r[cfg.target_pointer_width.values] @@ -247,7 +247,7 @@ Example values: r[cfg.target_vendor] ### `target_vendor` -r[cfg.target_vendor.general] +r[cfg.target_vendor.def] Key-value option set once with the vendor of the target. r[cfg.target_vendor.values] @@ -261,7 +261,7 @@ Example values: r[cfg.target_has_atomic] ### `target_has_atomic` -r[cfg.target_has_atomic.general] +r[cfg.target_has_atomic.def] Key-value option set for each bit width that the target supports atomic loads, stores, and compare-and-swap operations. @@ -302,7 +302,7 @@ Set when the crate being compiled is being compiled with the `proc_macro` r[cfg.panic] ### `panic` -r[cfg.panic.general] +r[cfg.panic.def] Key-value option set depending on the [panic strategy]. Note that more values may be added in the future. r[cfg.panic.values] diff --git a/src/const_eval.md b/src/const_eval.md index fcf3f05d22..779b00354e 100644 --- a/src/const_eval.md +++ b/src/const_eval.md @@ -1,13 +1,13 @@ r[const-eval] # Constant evaluation -r[const-eval.general] +r[const-eval.intro] Constant evaluation is the process of computing the result of [expressions] during compilation. Only a subset of all expressions can be evaluated at compile-time. r[const-eval.const-expr] ## Constant expressions -r[const-eval.const-expr.general] +r[const-eval.const-expr.intro] Certain forms of expressions, called constant expressions, can be evaluated at compile time. r[const-eval.const-expr.const-context] @@ -236,7 +236,7 @@ r[const-eval.const-context] ## Const context [const context]: #const-context -r[const-eval.const-context.general] +r[const-eval.const-context.def] A _const context_ is one of the following: r[const-eval.const-context.array-length] diff --git a/src/crates-and-source-files.md b/src/crates-and-source-files.md index 1ace243ad5..e5cdf6bf8a 100644 --- a/src/crates-and-source-files.md +++ b/src/crates-and-source-files.md @@ -77,7 +77,7 @@ apply to the crate as a whole. r[crate.main] ## Main functions -r[crate.main.general] +r[crate.main.executable] A crate that contains a `main` [function] can be compiled to an executable. r[crate.main.restriction] diff --git a/src/items/implementations.md b/src/items/implementations.md index 205d6f72fd..4838c6f04c 100644 --- a/src/items/implementations.md +++ b/src/items/implementations.md @@ -180,7 +180,7 @@ An orphan implementation is one that implements a foreign trait for a foreign ty The orphan rule enables library authors to add new implementations to their traits without fear that they'll break downstream code. Without these restrictions, a library couldn't add an implementation like `impl MyTrait for T` without potentially conflicting with downstream implementations. -r[items.impl.trait.orphan-rule.general] +r[items.impl.trait.orphan-rule.def] Given `impl Trait for T0`, an `impl` is valid only if at least one of the following is true: diff --git a/src/type-layout.md b/src/type-layout.md index 24a9b4dbfd..771803fbb1 100644 --- a/src/type-layout.md +++ b/src/type-layout.md @@ -114,7 +114,7 @@ String slices are a UTF-8 representation of characters that have the same layout r[layout.tuple] ## Tuple layout -r[layout.tuple.general] +r[layout.tuple.def] Tuples are laid out according to the [`Rust` representation][`Rust`]. r[layout.tuple.unit]