diff --git a/library/core/src/attribute_docs.rs b/library/core/src/attribute_docs.rs index 94ff7a8fee6d3..8096778f3f517 100644 --- a/library/core/src/attribute_docs.rs +++ b/library/core/src/attribute_docs.rs @@ -194,6 +194,52 @@ 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_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 +370,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 +450,209 @@ 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 from being 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 warn on compilation if the `expect`ed lint +/// wasn't emitted. +/// +/// 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 +/// #[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 unfulfilled 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 {}