Rollup merge of #147586 - folkertdev:std-detect-expands-to-true, r=Amanieu

std-detect: improve detect macro docs

Specifically, document that the detect macros expand to `true` when the feature is statically enabled.

Now that we have a bunch of these macros, perhaps we should streamline further how they are documented?

r? ``@Amanieu``

Author: Zalathar

library/std_detect/src/detect/arch/aarch64.rs

@@ -5,13 +5,18 @@ features! {
     @CFG: any(target_arch = "aarch64", target_arch = "arm64ec");
     @MACRO_NAME: is_aarch64_feature_detected;
     @MACRO_ATTRS:
-    /// This macro tests, at runtime, whether an `aarch64` feature is enabled on aarch64 platforms.
-    /// Currently most features are only supported on linux-based platforms.
+    /// Check for the presence of a CPU feature at runtime.
+    ///
+    /// When the feature is known to be enabled at compile time (e.g. via `-Ctarget-feature`)
+    /// the macro expands to `true`.
     ///
     /// This macro takes one argument which is a string literal of the feature being tested for.
     /// The feature names are mostly taken from their FEAT_* definitions in the [ARM Architecture
     /// Reference Manual][docs].
     ///
+    /// Currently most features are only supported on linux-based platforms: on other platforms the
+    /// runtime check will always return `false`.
+    ///
     /// ## Supported arguments
     ///
     /// * `"aes"` - FEAT_AES & FEAT_PMULL

library/std_detect/src/detect/arch/arm.rs

@@ -5,7 +5,10 @@ features! {
     @CFG: target_arch = "arm";
     @MACRO_NAME: is_arm_feature_detected;
     @MACRO_ATTRS:
-    /// Checks if `arm` feature is enabled.
+    /// Check for the presence of a CPU feature at runtime.
+    ///
+    /// When the feature is known to be enabled at compile time (e.g. via `-Ctarget-feature`)
+    /// the macro expands to `true`.
     #[unstable(feature = "stdarch_arm_feature_detection", issue = "111190")]
     @NO_RUNTIME_DETECTION: "v7";
     @NO_RUNTIME_DETECTION: "vfp2";

library/std_detect/src/detect/arch/loongarch.rs

@@ -5,7 +5,11 @@ features! {
     @CFG: any(target_arch = "loongarch32", target_arch = "loongarch64");
     @MACRO_NAME: is_loongarch_feature_detected;
     @MACRO_ATTRS:
-    /// Checks if `loongarch` feature is enabled.
+    /// Check for the presence of a CPU feature at runtime.
+    ///
+    /// When the feature is known to be enabled at compile time (e.g. via `-Ctarget-feature`)
+    /// the macro expands to `true`.
+    ///
     /// Supported arguments are:
     ///
     /// * `"32s"`

library/std_detect/src/detect/arch/mips.rs

@@ -5,7 +5,10 @@ features! {
     @CFG: target_arch = "mips";
     @MACRO_NAME: is_mips_feature_detected;
     @MACRO_ATTRS:
-    /// Checks if `mips` feature is enabled.
+    /// Check for the presence of a CPU feature at runtime.
+    ///
+    /// When the feature is known to be enabled at compile time (e.g. via `-Ctarget-feature`)
+    /// the macro expands to `true`.
     #[unstable(feature = "stdarch_mips_feature_detection", issue = "111188")]
     @FEATURE: #[unstable(feature = "stdarch_mips_feature_detection", issue = "111188")] msa: "msa";
     /// MIPS SIMD Architecture (MSA)

library/std_detect/src/detect/arch/mips64.rs

@@ -5,7 +5,10 @@ features! {
     @CFG: target_arch = "mips64";
     @MACRO_NAME: is_mips64_feature_detected;
     @MACRO_ATTRS:
-    /// Checks if `mips64` feature is enabled.
+    /// Check for the presence of a CPU feature at runtime.
+    ///
+    /// When the feature is known to be enabled at compile time (e.g. via `-Ctarget-feature`)
+    /// the macro expands to `true`.
     #[unstable(feature = "stdarch_mips_feature_detection", issue = "111188")]
     @FEATURE: #[unstable(feature = "stdarch_mips_feature_detection", issue = "111188")] msa: "msa";
     /// MIPS SIMD Architecture (MSA)

library/std_detect/src/detect/arch/powerpc.rs

@@ -5,7 +5,10 @@ features! {
     @CFG: target_arch = "powerpc";
     @MACRO_NAME: is_powerpc_feature_detected;
     @MACRO_ATTRS:
-    /// Checks if `powerpc` feature is enabled.
+    /// Check for the presence of a CPU feature at runtime.
+    ///
+    /// When the feature is known to be enabled at compile time (e.g. via `-Ctarget-feature`)
+    /// the macro expands to `true`.
     #[unstable(feature = "stdarch_powerpc_feature_detection", issue = "111191")]
     @FEATURE: #[unstable(feature = "stdarch_powerpc_feature_detection", issue = "111191")] altivec: "altivec";
     /// Altivec

library/std_detect/src/detect/arch/powerpc64.rs

@@ -5,7 +5,10 @@ features! {
     @CFG: target_arch = "powerpc64";
     @MACRO_NAME: is_powerpc64_feature_detected;
     @MACRO_ATTRS:
-    /// Checks if `powerpc` feature is enabled.
+    /// Check for the presence of a CPU feature at runtime.
+    ///
+    /// When the feature is known to be enabled at compile time (e.g. via `-Ctarget-feature`)
+    /// the macro expands to `true`.
     #[unstable(feature = "stdarch_powerpc_feature_detection", issue = "111191")]
     @FEATURE: #[unstable(feature = "stdarch_powerpc_feature_detection", issue = "111191")] altivec: "altivec";
     /// Altivec

library/std_detect/src/detect/arch/riscv.rs

@@ -5,8 +5,10 @@ features! {
     @CFG: any(target_arch = "riscv32", target_arch = "riscv64");
     @MACRO_NAME: is_riscv_feature_detected;
     @MACRO_ATTRS:
-    /// A macro to test at *runtime* whether instruction sets are available on
-    /// RISC-V platforms.
+    /// Check for the presence of a CPU feature at runtime.
+    ///
+    /// When the feature is known to be enabled at compile time (e.g. via `-Ctarget-feature`)
+    /// the macro expands to `true`.
     ///
     /// RISC-V standard defined the base sets and the extension sets.
     /// The base sets are RV32I, RV64I, RV32E or RV128I. Any RISC-V platform

library/std_detect/src/detect/arch/s390x.rs

@@ -5,7 +5,10 @@ features! {
     @CFG: target_arch = "s390x";
     @MACRO_NAME: is_s390x_feature_detected;
     @MACRO_ATTRS:
-    /// Checks if `s390x` feature is enabled.
+    /// Check for the presence of a CPU feature at runtime.
+    ///
+    /// When the feature is known to be enabled at compile time (e.g. via `-Ctarget-feature`)
+    /// the macro expands to `true`.
     #[unstable(feature = "stdarch_s390x_feature_detection", issue = "135413")]
     @FEATURE: #[unstable(feature = "stdarch_s390x_feature_detection", issue = "135413")] concurrent_functions: "concurrent-functions";
     /// s390x concurrent-functions facility

library/std_detect/src/detect/arch/x86.rs

@@ -20,13 +20,12 @@ features! {
     @CFG: any(target_arch = "x86", target_arch = "x86_64");
     @MACRO_NAME: is_x86_feature_detected;
     @MACRO_ATTRS:
-    /// A macro to test at *runtime* whether a CPU feature is available on
-    /// x86/x86-64 platforms.
+    /// Check for the presence of a CPU feature at runtime.
     ///
-    /// This macro is provided in the standard library and will detect at runtime
-    /// whether the specified CPU feature is detected. This does **not** resolve at
-    /// compile time unless the specified feature is already enabled for the entire
-    /// crate. Runtime detection currently relies mostly on the `cpuid` instruction.
+    /// When the feature is known to be enabled at compile time (e.g. via `-Ctarget-feature`)
+    /// the macro expands to `true`.
+    ///
+    /// Runtime detection currently relies mostly on the `cpuid` instruction.
     ///
     /// This macro only takes one argument which is a string literal of the feature
     /// being tested for. The feature names supported are the lowercase versions of