From c38a17d11068fabf5d8967a3deef71448e50b450 Mon Sep 17 00:00:00 2001 From: Emmanuel Ugwu Date: Wed, 1 Jul 2026 16:31:53 +0100 Subject: [PATCH 1/3] Attribute documentation for used, expect, should_panic, cfg_attr, path, and ignore Signed-off-by: Emmanuel Ugwu --- library/core/src/attribute_docs.rs | 255 ++++++++++++++++++++++++++++- 1 file changed, 254 insertions(+), 1 deletion(-) diff --git a/library/core/src/attribute_docs.rs b/library/core/src/attribute_docs.rs index 94ff7a8fee6d3..91f5d440f3a9e 100644 --- a/library/core/src/attribute_docs.rs +++ b/library/core/src/attribute_docs.rs @@ -194,6 +194,53 @@ mod allow_attribute {} /// [`if`]: ./keyword.if.html mod cfg_attribute {} +#[doc(attribute = "cfg_attr")] +// +/// The `cfg_attr` attribute is used to conditionally apply one or more attributes to an item. +/// +/// Example: +/// +/// ```rust +/// // This function is annotated with `#[test]` only on Linux platforms. +/// #[cfg_attr(target_os = "linux", test)] +/// fn my_function() { +/// // ... +/// } +/// ``` +/// +/// You can apply multiple attributes by separating them with commas: +/// +/// ```rust +/// #[cfg_attr(feature = "nightly", allow(dead_code), deny(unused_variables))] +/// // This function only gets the `allow(dead_code)` and `deny(unused_variables)` attributes when +/// // `feature = "nightly"` is active. +/// fn nightly_only_function() { +/// let x = 42; +/// } +/// ``` +/// +/// For complex conditions, you can combine `all(...)`, `any(...)`, and `not(...)`. +/// +/// * `all`: True if all given predicates are true. +/// * `any`: True if at least one of the given predicates is true. +/// * `not`: True if the predicate is false. +/// +/// ```rust +/// #[cfg_attr( +/// all(feature = "system", feature = "disk"), +/// doc = "For module documentation, both `system`, and `disk` need to be enabled.", +/// )] +/// mod my_module { +/// // ... +/// } +/// ``` +/// +/// For more information, see the Reference on [the `cfg_attr` attribute]. +/// +/// [the `cfg` attribute]: ../reference/conditional-compilation.html#the-cfg-attribute +/// [the `cfg_attr` attribute]: ../reference/conditional-compilation.html#the-cfg_attr-attribute +mod cfg_attr_attribute {} + #[doc(attribute = "deny")] // /// Emits an error, preventing the compilation from finishing, when a lint check has failed. @@ -324,7 +371,6 @@ mod deprecated_attribute {} /// } /// ``` /// -/// /// Many lints, including `unused`, are already set to `warn` by default so this attribute is /// mainly useful for lints that are normally [`allow`] by default. /// @@ -405,3 +451,210 @@ mod warn_attribute {} /// [`Result`]: result::Result /// [the `no_std` attribute]: ../reference/names/preludes.html#the-no_std-attribute mod no_std_attribute {} + +#[doc(attribute = "used")] +// +/// The `#[used]` attribute can be used on static variables to prevent the Rust compiler +/// from optimizing them away even if they are not used in the current crate. +/// +/// It tells the compiler that an item is still in use or needed elsewhere and, because of this, +/// should be kept in the files generated by `rustc` when compiling. +/// +/// Example: +/// +/// ```rust +/// #[used] +/// static FOO: u16 = 42; // FOO is not optimized away as dead code. +/// +/// static BAR: u16 = 12; // BAR may be optimized away. +/// ``` +/// +/// To confirm, we compile this code and then we confirm that `FOO` is present in the generated files, +/// but not `BAR`. +/// +/// ```shell +/// $ rustc -C opt-level=3 --emit=obj used.rs +/// $ nm -C used.o +/// 0000000000000000 T main +/// U std::rt::lang_start_internal +/// 0000000000000000 T std::rt::lang_start +/// 0000000000000000 t std::rt::lang_start::{{closure}} +/// 0000000000000000 t std::sys::backtrace::__rust_begin_short_backtrace +/// 0000000000000000 t core::ops::function::FnOnce::call_once{{vtable.shim}} +/// 0000000000000000 r used::FOO +/// 0000000000000000 T used::main +/// ``` +/// +/// For more information, see the Reference on [the `used` attribute]. +/// +/// [the `used` attribute]: ../reference/abi.html#the-used-attribute +mod used_attribute {} + +#[doc(attribute = "ignore")] +// +/// The `ignore` attribute is used alongside the `test` attribute to prevent this test to be run by default. +/// The `ignore` attribute may only be applied to functions annotated with the `test` attribute. +/// +/// Example: +/// +/// ```rust +/// #[test] +/// #[ignore] +/// fn test() { +/// // ... This test is ignored by the test harness (the compiler still compiles it). +/// } +/// ``` +/// +/// The `ignore` attribute can be very useful when a test is incomplete but we still want to compile it. +/// +/// To run ignored tests, use `cargo test -- --ignored` or with `rustc` using the `--include-ignored` +/// flag. +/// +/// For more information, see the Reference on [the `ignore` attribute]. +/// +/// [the `ignore` attribute]: ../reference/attributes/testing.html#the-ignore-attribute +mod ignore_attribute {} + +#[doc(attribute = "expect")] +// +/// The `#[expect]` attribute declares that a particular lint is expected to be emitted. +/// It is an equivalent of the `allow` attribute, except that it will fail compilation if the `expect`ed lint +/// wasn't emitted. +/// +/// `expect` can be overridden by `warn`, `allow`, `deny`, and `forbid`. +/// +/// Example: +/// +/// ```rust +/// #[expect(unused_variables)] +/// let name = "rust-lang"; // The `unused_variables` warning is suppressed. +/// ``` +/// +/// Here is an example where the `expect`ed lint is not emitted: +/// +/// ```rust,compile_fail +/// #[expect(unused_variables)] +/// let name = "rust-lang"; +/// println!("{name}"); +/// ```` +/// +/// In the example above the variable is used, so the `expect` is unfufilled this warning is emitted: +/// +/// ```text +/// warning: this lint expectation is unfulfilled +/// --> example.rs:2:14 +/// | +/// 2 | #[expect(unused_variables)] +/// | ^^^^^^^^^^^^^^^^ +/// | +/// = note: `#[warn(unfulfilled_lint_expectations)]` on by default +/// +/// warning: 1 warning emitted +/// ``` +/// +/// Multiple lints can be set to `expect` at once, each one is expected separately. +/// +/// ```rust,compile_fail +/// #[expect(unused_mut, unused_variables)] +/// fn main() { +/// // This attribute creates two lint expectations. The `unused_mut` lint will be +/// // suppressed and with that fulfill the first expectation. The `unused_variables` +/// // wouldn't be emitted, since the variable is used. That expectation will therefore +/// // be unsatisfied, and a warning will be emitted. +/// let mut x = 42; +/// println!("x: {x}"); +/// } +/// ``` +/// +/// For a lint group, it’s enough if one lint inside the group has been emitted: +/// +/// ```rust +/// // The lint group is fulfilled as the variables are unused. +/// #[expect(unused)] +/// let x = 10; +/// let y = 12; +/// ``` +/// +/// For more information, see the Reference on [the `expect` attribute]. +/// +/// [the `expect` attribute]: ../reference/attributes/diagnostics.html#lint-check-attributes +mod expect_attribute {} + +#[doc(attribute = "should_panic")] +// +/// The `should_panic` attribute is used alongside the `test` attribute to indicate that a test is expected +/// to panic and will fail if it doesn't. +/// +/// The `should_panic` attribute may only be applied to functions annotated with the `test` attribute. +/// +/// ```rust,no_run +/// #[test] +/// fn test_add() { +/// assert_eq!(2 + 3, 5); // This test passes. +/// } +/// +/// #[test] +/// #[should_panic] +/// fn test_add_neg() { +/// assert_eq!(-1 + 1, 10); // Panics (0 != 10), so the test passes. +/// } +/// +/// #[test] +/// #[should_panic] +/// fn failing_test() { +/// panic!("This test is meant to panic"); // This test passes. +/// } +/// +/// #[test] +/// #[should_panic] +/// fn test_without_panic() { +/// println!("A test that does not panic"); +/// } +/// ``` +/// +/// The `test_without_panic` function fails as it is expected to panic: +/// +/// ```text +/// test test_without_panic - should panic ... FAILED +/// ``` +/// +/// For more information, see the Reference on [the `should_panic` attribute]. +/// +/// [the `should_panic` attribute]: ../reference/attributes/testing.html#the-should_panic-attribute +mod should_panic_attribute {} + +#[doc(attribute = "path")] +// +/// The `#[path = "..."]` attribute tells the compiler where to find a module's source file, overriding the default +/// file lookup. +/// +/// Example: +/// +/// ```rust,compile_fail +/// mod foo; // By default `rustc` loads the source from `foo.rs`. +/// ``` +/// +/// The `path` attribute overrides this behavior: +/// +/// ```rust,compile_fail +/// #[path = "bar.rs"] +/// mod foo; // Now bar.rs is loaded as foo. +/// ``` +/// The `path` attribute accept both absolute and relative file paths: +/// +/// ```rust,compile_fail +/// // src/main.rs +/// #[path = "bar/foo.rs"] +/// mod foo; // `rustc` looks for the module at src/bar/foo.rs. +/// ``` +/// +///```rust,compile_fail +/// // lib/src/lib.rs +/// #[path = "../utils/utils.rs"] +/// mod utilities; // `rustc` looks for the module at lib/utils/utils.rs. +///``` +/// +/// For more information, see the Reference on [the `path` attribute]. +/// +/// [the `path` attribute]: ../reference/items/modules.html#the-path-attribute +mod path_attribute {} From ec52be71a8a7343543e52fa054e1719526285034 Mon Sep 17 00:00:00 2001 From: Emmanuel Ugwu Date: Fri, 10 Jul 2026 16:20:42 +0100 Subject: [PATCH 2/3] address feedback Signed-off-by: Emmanuel Ugwu --- library/core/src/attribute_docs.rs | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/library/core/src/attribute_docs.rs b/library/core/src/attribute_docs.rs index 91f5d440f3a9e..856cb51738f5a 100644 --- a/library/core/src/attribute_docs.rs +++ b/library/core/src/attribute_docs.rs @@ -228,7 +228,7 @@ mod cfg_attribute {} /// ```rust /// #[cfg_attr( /// all(feature = "system", feature = "disk"), -/// doc = "For module documentation, both `system`, and `disk` need to be enabled.", +/// doc = "For module documentation, both `system` and `disk` need to be enabled.", /// )] /// mod my_module { /// // ... @@ -492,7 +492,7 @@ mod used_attribute {} #[doc(attribute = "ignore")] // -/// The `ignore` attribute is used alongside the `test` attribute to prevent this test to be run by default. +/// The `ignore` attribute is used alongside the `test` attribute to prevent this test from being run by default. /// The `ignore` attribute may only be applied to functions annotated with the `test` attribute. /// /// Example: @@ -518,11 +518,9 @@ mod ignore_attribute {} #[doc(attribute = "expect")] // /// The `#[expect]` attribute declares that a particular lint is expected to be emitted. -/// It is an equivalent of the `allow` attribute, except that it will fail compilation if the `expect`ed lint +/// It is an equivalent of the `allow` attribute, except that it will warn on compilation if the `expect`ed lint /// wasn't emitted. /// -/// `expect` can be overridden by `warn`, `allow`, `deny`, and `forbid`. -/// /// Example: /// /// ```rust @@ -532,13 +530,14 @@ mod ignore_attribute {} /// /// Here is an example where the `expect`ed lint is not emitted: /// -/// ```rust,compile_fail +/// ```rust +/// #[deny(unfulfilled_lint_expectations)] /// #[expect(unused_variables)] /// let name = "rust-lang"; /// println!("{name}"); -/// ```` +/// ``` /// -/// In the example above the variable is used, so the `expect` is unfufilled this warning is emitted: +/// In the example above the variable is used, so the `expect` is unfulfilled this warning is emitted: /// /// ```text /// warning: this lint expectation is unfulfilled @@ -570,7 +569,7 @@ mod ignore_attribute {} /// /// ```rust /// // The lint group is fulfilled as the variables are unused. -/// #[expect(unused)] +/// #![expect(unused)] /// let x = 10; /// let y = 12; /// ``` From d4258a2c85fd582ce1cd214a46a0ecba19aaba4c Mon Sep 17 00:00:00 2001 From: Emmanuel Ugwu Date: Fri, 10 Jul 2026 16:25:13 +0100 Subject: [PATCH 3/3] remove cfg link in cfg_attr Signed-off-by: Emmanuel Ugwu --- library/core/src/attribute_docs.rs | 1 - 1 file changed, 1 deletion(-) diff --git a/library/core/src/attribute_docs.rs b/library/core/src/attribute_docs.rs index 856cb51738f5a..8096778f3f517 100644 --- a/library/core/src/attribute_docs.rs +++ b/library/core/src/attribute_docs.rs @@ -237,7 +237,6 @@ mod cfg_attribute {} /// /// For more information, see the Reference on [the `cfg_attr` attribute]. /// -/// [the `cfg` attribute]: ../reference/conditional-compilation.html#the-cfg-attribute /// [the `cfg_attr` attribute]: ../reference/conditional-compilation.html#the-cfg_attr-attribute mod cfg_attr_attribute {}