Attribute documentation for used, expect, should_panic, cfg_attr, and path

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 {}