update documentation

move the entirety of the unstable `-Clinker-features` documentation to
the stable book, as there's only a single feature, and it is now stable

Author: lqd

src/doc/rustc/src/codegen-options/index.md

@@ -244,18 +244,35 @@ flag for another way to specify the linker.
 
 ## linker-features
 
-This flag allows enabling or disabling specific features used during linking.
+The `-Clinker-features` flag allows enabling or disabling specific features used during linking.
 
-The flag accepts a comma-separated list of features, individually enabled (`+feature`) or disabled
-(`-feature`).
+These feature flags are a flexible extension mechanism that is complementary to linker flavors,
+designed to avoid the combinatorial explosion of having to create a new set of flavors for each
+linker feature we'd want to use.
 
-Currently, only one such feature is stable:
-- `lld`: toggles the usage of the lld linker, either the system-installed binary, or the self-contained
-  `rust-lld` linker.
+The flag accepts a comma-separated list of features, individually enabled (`+features`) or disabled
+(`-features`).
 
-If you want to opt out of the usage of the `lld` linker (for targets where it is configured as the default linker),
+Currently only one is stable, and only on the `x86_64-unknown-linux-gnu` target:
+- `lld`: to toggle using the lld linker, either the system-installed binary, or the self-contained
+  `rust-lld` linker (via the `-Clink-self-contained=+linker` flag).
+
+To opt out of using the `lld` linker (for targets where it is configured as the default linker),
 use `-Clinker-features=-lld`.
 
+In general, this design allows:
+- default feature sets for principal flavors, or for specific targets.
+- flavor-specific features: for example, clang offers automatic cross-linking with `--target`, which
+  gcc-style compilers don't support. The *flavor* is still a C/C++ compiler, and we don't want to
+  multiply the number of flavors for this use-case. Instead, we can have a single `+target` feature.
+- umbrella features: for example, if clang accumulates more features in the future than just the
+  `+target` above. That could be modeled as `+clang`.
+- niche features for resolving specific issues: for example, on Apple targets the linker flag
+  implementing the `as-needed` native link modifier ([#99424](https://github.com/rust-lang/rust/issues/99424))
+  is only possible on sufficiently recent linker versions.
+- still allows for discovery and automation, for example via feature detection. This can be useful
+  in exotic environments/build systems.
+
 ## linker-flavor
 
 This flag controls the linker flavor used by `rustc`. If a linker is given with