Add some documentation about unstable namespaced-features feature

diff --git a/src/doc/src/reference/unstable.md b/src/doc/src/reference/unstable.md
index 483e5e2537ea7d72f1f6e6ae23644d4c50452811..ca004ccce62e7a166fdae9d47c28624cc148123d 100644 (file)
--- a/src/doc/src/reference/unstable.md
+++ b/src/doc/src/reference/unstable.md
@@ -227,3 +227,30 @@ opt-level = 3
 ```
 
 Overrides can only be specified for dev and release profiles.
+
+
+### Namespaced features
+* Original issue: [#1286](https://github.com/rust-lang/cargo/issues/1286)
+
+Currently, it is not possible to have a feature and a dependency with the same
+name in the manifest. If you set `namespaced-features` to `true`, the namespaces
+for features and dependencies are separated. The effect of this is that, in the
+feature requirements, dependencies have to be prefixed with `crate:`. Like this:
+
+```toml
+[project]
+namespaced-features = true
+
+[features]
+bar = ["crate:baz", "foo"]
+foo = []
+
+[dependencies]
+baz = { version = "0.1", optional = true }
+```
+
+To prevent unnecessary boilerplate from having to explicitly declare features
+for each optional dependency, implicit features get created for any optional
+dependencies where a feature of the same name is not defined. However, if
+a feature of the same name as a dependency is defined, that feature must
+include the dependency as a requirement, as `foo = ["crate:foo"]`.