From df7af8d33355eb10828f32e1c571d97eaf3a59ce Mon Sep 17 00:00:00 2001
From: 0xPoe <poe.liu@pm.me>
Date: Mon, 5 Oct 2026 15:38:16 +0200
Subject: [PATCH] docs(hints): write mostly-unused docs as end-user
 documentation

Signed-off-by: 0xPoe <poe.liu@pm.me>
---
 doc/book/src/reference/unstable.md | 69 ++++++++++++++++++++++++++++++
 1 file changed, 69 insertions(+)

diff --git a/doc/book/src/reference/unstable.md b/doc/book/src/reference/unstable.md
index e53b89a0a3f..f386ef9f7cf 100644
--- a/doc/book/src/reference/unstable.md
+++ b/doc/book/src/reference/unstable.md
@@ -942,6 +942,75 @@ This will cause the crate to default to hint-mostly-unused, unless overridden
 via `profile`, which takes precedence, and which can only be specified in the
 top-level crate being built.
 
+### Documentation updates
+
+#### hint-mostly-unused
+
+*as a new ["Profile settings" entry](./profiles.html#profile-settings)*
+
+The `hint-mostly-unused` setting controls the [`-Zhint-mostly-unused` flag]
+which indicates that most of a crate's API surface will go unused by anything
+depending on it. This hint can speed up the build by attempting to minimize
+compilation time for items that aren't used at all. Misapplication to crates
+that don't fit that criteria can slow down the build rather than speeding it
+up.
+
+The valid options are:
+
+* `true`: enabled
+* `false`: disabled
+
+The default is the crate's [`mostly-unused` hint](#mostly-unused), or `false`
+if the crate does not set the hint.
+
+This is primarily useful to enable for specific dependencies:
+
+```toml
+[profile.dev.package.huge-mostly-unused-dependency]
+hint-mostly-unused = true
+```
+
+The [`blanket_hint_mostly_unused`] lint warns when this setting is applied to
+all dependencies.
+
+[`-Zhint-mostly-unused` flag]: ../../unstable-book/compiler-flags/hint-mostly-unused.html
+[`blanket_hint_mostly_unused`]: lints.md#blanket_hint_mostly_unused
+
+#### `mostly-unused`
+
+*as a new subsection of ["The `[hints]` section"](./manifest.html#the-hints-section),
+which would gain one subsection per hint*
+
+The `mostly-unused` hint indicates that most of this crate's API surface will
+go unused by anything depending on it. A crate can provide this hint
+automatically for crates that depend on it:
+
+```toml
+# In example-dependency's Cargo.toml
+[hints]
+mostly-unused = true
+```
+
+This will cause the crate to default to
+[`hint-mostly-unused`](#hint-mostly-unused). A `hint-mostly-unused` setting in
+a [profile](profiles.md) takes precedence over the hint. Only the workspace
+root `Cargo.toml` and [Cargo configuration](config.md#profile) can set
+profiles:
+
+```toml
+# This package uses most of `example-dependency`, so the hint does not apply.
+[profile.dev.package.example-dependency]
+hint-mostly-unused = false
+```
+
+The valid values are `true` and `false`. Cargo warns about and ignores any
+other value.
+
+A hint only applies to the package that sets it, not to its dependencies.
+
+Only use this hint when you expect most dependents to use a small part of the
+crate. Otherwise, the hint may slow down their builds.
+
 ## Package `min-opt-level` hint
 * Tracking Issue: [#17334](https://github.com/rust-lang/cargo/issues/17334)
 * RFC: [#3924](https://github.com/rust-lang/rfcs/pull/3924)