3 files changed, 81 insertions, 17 deletions

diff --git a/src/libutil/config.hh b/src/libutil/config.hh
index 3c1d70294..a001056f7 100644
--- a/src/libutil/config.hh
+++ b/src/libutil/config.hh
@@ -372,7 +372,7 @@ extern GlobalConfig globalConfig;
 struct ExperimentalFeatureSettings : Config {
 
     Setting<std::set<ExperimentalFeature>> experimentalFeatures{this, {}, "experimental-features",
-        "Experimental Nix features to enable."};
+        getExperimentalFeaturesList()};
 
     /**
      * Check whether the given experimental feature is enabled.
diff --git a/src/libutil/experimental-features.cc b/src/libutil/experimental-features.cc
index 58d762ebb..fc8590674 100644
--- a/src/libutil/experimental-features.cc
+++ b/src/libutil/experimental-features.cc
@@ -5,18 +5,61 @@
 
 namespace nix {
 
-std::map<ExperimentalFeature, std::string> stringifiedXpFeatures = {
-    { Xp::CaDerivations, "ca-derivations" },
-    { Xp::ImpureDerivations, "impure-derivations" },
-    { Xp::Flakes, "flakes" },
-    { Xp::NixCommand, "nix-command" },
-    { Xp::RecursiveNix, "recursive-nix" },
-    { Xp::NoUrlLiterals, "no-url-literals" },
-    { Xp::FetchClosure, "fetch-closure" },
-    { Xp::ReplFlake, "repl-flake" },
-    { Xp::AutoAllocateUids, "auto-allocate-uids" },
-    { Xp::Cgroups, "cgroups" },
-    { Xp::DiscardReferences, "discard-references" },
+std::map<ExperimentalFeature, std::pair<std::string, std::string>> stringifiedXpFeatures = {
+    { Xp::CaDerivations, {"ca-derivations", R"(
+      Allows derivations to be content-addressed in order to prevent rebuilds
+      when changes to the derivation do not result in changes to the
+      derivation's output. See
+      [__contentAddressed](../language/advanced-attributes.md#adv-attr-__contentAddressed)
+      for more info.
+    )"} },
+    { Xp::ImpureDerivations, {"impure-derivations", R"(
+      Allows derivations to produce non-fixed outputs by setting the `__impure`
+      derivation attribute to `true`. See [these release
+      notes](../release-notes/rl-2.8.md) for an example.
+    )"} },
+    { Xp::Flakes, {"flakes", R"(
+      Allows for derivations to be packaged in flakes. See the manual entry for
+      [`nix flake`](../command-ref/new-cli/nix3-flake.md) or this [detailed
+      introduction](https://www.tweag.io/blog/2020-05-25-flakes/) for more info.
+    )"} },
+    { Xp::NixCommand, {"nix-command", R"(
+      Allows the usage of the new `nix` CLI subcommands, such as `nix build`, `nix
+      develop`, `nix run`, etc. See the manual for
+      [`nix`](../command-ref/new-cli/nix.md) for more info.
+    )"} },
+    { Xp::RecursiveNix, {"recursive-nix", R"(
+      Allow Nix derivations to call Nix in order to recursively build derivations.
+      See [this
+      commit](https://github.com/edolstra/nix/commit/1a27aa7d64ffe6fc36cfca4d82bdf51c4d8cf717)
+      for more info.
+    )"} },
+    { Xp::NoUrlLiterals, {"no-url-literals", R"(
+      Disallows unquoted URLs as part of the Nix language syntax. See [RFC
+      45](https://github.com/NixOS/rfcs/pull/45) for more info.
+    )"} },
+    { Xp::FetchClosure, {"fetch-closure", R"(
+      Enables the use of the `fetchClosure` function in the standard library. See
+      the docs for [`fetchClosure`](../language/builtins.md#builtins-fetchClosure)
+      for more info.
+    )"} },
+    { Xp::ReplFlake, {"repl-flake", R"(
+      Allows the user to enter a Nix REPL within a flake, e.g. `nix repl nixpkgs`
+      or `nix repl .#foo`.
+    )"} },
+    { Xp::AutoAllocateUids, {"auto-allocate-uids", R"(
+      Allows Nix to automatically pick UIDs for builds, rather than creating
+      `nixbld*` user accounts. See [here](#conf-auto-allocate-uids) for more info.
+    )"} },
+    { Xp::Cgroups, {"cgroups", R"(
+      Allows Nix to execute builds inside cgroups. See
+      [`use-cgroups`](#conf-use-cgroups) for more info.
+    )"} },
+    { Xp::DiscardReferences, {"discard-references", R"(
+      Enables the use of the `unsafeDiscardReferences` attribute in derivations
+      that use structured attributes. This disables scanning of outputs for
+      runtime dependencies.
+    )"} },
 };
 
 const std::optional<ExperimentalFeature> parseExperimentalFeature(const std::string_view & name)
@@ -26,8 +69,11 @@ const std::optional<ExperimentalFeature> parseExperimentalFeature(const std::str
     static auto reverseXpMap = []()
     {
         auto reverseXpMap = std::make_unique<ReverseXpMap>();
-        for (auto & [feature, name] : stringifiedXpFeatures)
+        std::string_view name;
+        for (auto & [feature, featureStringPair] : stringifiedXpFeatures) {
+            name = featureStringPair.first;
             (*reverseXpMap)[name] = feature;
+        }
         return reverseXpMap;
     }();
 
@@ -41,7 +87,24 @@ std::string_view showExperimentalFeature(const ExperimentalFeature feature)
 {
     const auto ret = get(stringifiedXpFeatures, feature);
     assert(ret);
-    return *ret;
+    return ret->first;
+}
+
+std::string getExperimentalFeaturesList() {
+    std::string experimentalFeaturesList = R"(
+    Experimental Nix features to enable.
+    Current experimental features are the following:
+
+)";
+
+    std::string experimentalFeatureString;
+    for (auto& [feature, featureStringPair] : stringifiedXpFeatures) {
+        experimentalFeatureString = "    - `" + featureStringPair.first + "`\n";
+        experimentalFeatureString += featureStringPair.second + "\n\n";
+        experimentalFeaturesList += experimentalFeatureString;
+    }
+
+    return experimentalFeaturesList;
 }
 
 std::set<ExperimentalFeature> parseFeatures(const std::set<std::string> & rawFeatures)
diff --git a/src/libutil/experimental-features.hh b/src/libutil/experimental-features.hh
index 5948ad7ad..7c2f872c5 100644
--- a/src/libutil/experimental-features.hh
+++ b/src/libutil/experimental-features.hh
@@ -11,8 +11,8 @@ namespace nix {
 /**
  * The list of available experimental features.
  *
- * If you update this, don’t forget to also change the map defining their
- * string representation in the corresponding `.cc` file.
+ * If you update this, don’t forget to also change the map defining their string
+ * representation and documentation in the corresponding `.cc` file as well.
  */
 enum struct ExperimentalFeature
 {
@@ -37,6 +37,7 @@ using Xp = ExperimentalFeature;
 const std::optional<ExperimentalFeature> parseExperimentalFeature(
         const std::string_view & name);
 std::string_view showExperimentalFeature(const ExperimentalFeature);
+std::string getExperimentalFeaturesList();
 
 std::ostream & operator<<(
         std::ostream & str,