modules/mkRemovedOptionModule: add replacement doc

When displaying a warning about a removed Option we should always
include reasoning why it was removed and how to get the same
functionality without it.

Introduces such a description argument and patches occurences (mostly
with an empty string).

startGnuPGAgent: further notes on replacement

1 files changed, 10 insertions, 4 deletions

diff --git a/lib/modules.nix b/lib/modules.nix
index 12ec7004d1e..6e16fc68f67 100644
--- a/lib/modules.nix
+++ b/lib/modules.nix
@@ -503,19 +503,25 @@ rec {
   /* Return a module that causes a warning to be shown if the
      specified option is defined. For example,
 
-       mkRemovedOptionModule [ "boot" "loader" "grub" "bootDevice" ]
+       mkRemovedOptionModule [ "boot" "loader" "grub" "bootDevice" ] "<replacement instructions>"
 
      causes a warning if the user defines boot.loader.grub.bootDevice.
+
+     replacementInstructions is a string that provides instructions on
+     how to achieve the same functionality without the removed option,
+     or alternatively a reasoning why the functionality is not needed.
+     replacementInstructions SHOULD be provided!
   */
-  mkRemovedOptionModule = optionName:
+  mkRemovedOptionModule = optionName: replacementInstructions:
     { options, ... }:
     { options = setAttrByPath optionName (mkOption {
         visible = false;
       });
       config.warnings =
         let opt = getAttrFromPath optionName options; in
-        optional opt.isDefined
-          "The option definition `${showOption optionName}' in ${showFiles opt.files} no longer has any effect; please remove it.";
+        optional opt.isDefined ''
+            The option definition `${showOption optionName}' in ${showFiles opt.files} no longer has any effect; please remove it.
+            ${replacementInstructions}'';
     };
 
   /* Return a module that causes a warning to be shown if the