nixos/docs/option-declarations: Document mkEnableOption and mkPackageOption

This is a squashed commit. These are the original commit messages:

lib/option: Improve comment

better comment

Update documentation

Updated nixos/doc/manual/development/options-declarations.md with info on mkEnableOption and mkPackageOption.
Updated the comment on mkEnableOption in lib/options.nix

remove trailing whitespace

nixos/doc/option-declarations: Update IDs & formatting

nixos/docs/option-declarations: Escape angle brackets

Build DB from MD

(Amended) Fix typo
Co-authored-by: pennae <82953136+pennae@users.noreply.github.com>

(Amended) Build DB from MD (again)

1 files changed, 40 insertions, 15 deletions

diff --git a/lib/options.nix b/lib/options.nix
index b3a011168c3..794ca5e3394 100644
--- a/lib/options.nix
+++ b/lib/options.nix
@@ -100,23 +100,48 @@ rec {
     type = lib.types.bool;
   };
 
-  /* Creaties an Option attribute set for an option that specifies the
-     package a module should use.
+  /* Creates an Option attribute set for an option that specifies the
+     package a module should use for some purpose.
 
-     The argument default is an attribute set path in pkgs.
+     Type: mkPackageOption :: pkgs -> string -> { default :: [string], example :: null | string | [string] } -> option
+
+     The package is specified as a list of strings representing its attribute path in nixpkgs.
+
+     Because of this, you need to pass nixpkgs itself as the first argument.
+
+     The second argument is the name of the option, used in the description "The <name> package to use.".
+
+     You can also pass an example value, either a literal string or a package's attribute path.
+
+     You can omit the default path if the name of the option is also attribute path in nixpkgs.
+
+     Example:
+       mkPackageOption pkgs "hello" { }
+       => { _type = "option"; default = «derivation /nix/store/3r2vg51hlxj3cx5vscp0vkv60bqxkaq0-hello-2.10.drv»; defaultText = { ... }; description = "The hello package to use."; type = { ... }; }
+
+     Example:
+       mkPackageOption pkgs "GHC" {
+         default = [ "ghc" ];
+         example = "pkgs.haskell.package.ghc921.ghc.withPackages (hkgs: [ hkgs.primes ])";
+       }
+       => { _type = "option"; default = «derivation /nix/store/jxx55cxsjrf8kyh3fp2ya17q99w7541r-ghc-8.10.7.drv»; defaultText = { ... }; description = "The GHC package to use."; example = { ... }; type = { ... }; }
   */
-  mkPackageOption = pkgs: name:
-    { default ? [ name ], example ? null }:
-    let default' = if !isList default then [ default ] else default;
-    in mkOption {
-      type = lib.types.package;
-      description = "The ${name} package to use.";
-      default = attrByPath default'
-        (throw "${concatStringsSep "." default'} cannot be found in pkgs") pkgs;
-      defaultText = literalExpression ("pkgs." + concatStringsSep "." default');
-      ${if example != null then "example" else null} = literalExpression
-        (if isList example then "pkgs." + concatStringsSep "." example else example);
-    };
+  mkPackageOption =
+    # Package set (a specific version of nixpkgs)
+    pkgs:
+      # Name for the package, shown in option description
+      name:
+      { default ? [ name ], example ? null }:
+      let default' = if !isList default then [ default ] else default;
+      in mkOption {
+        type = lib.types.package;
+        description = "The ${name} package to use.";
+        default = attrByPath default'
+          (throw "${concatStringsSep "." default'} cannot be found in pkgs") pkgs;
+        defaultText = literalExpression ("pkgs." + concatStringsSep "." default');
+        ${if example != null then "example" else null} = literalExpression
+          (if isList example then "pkgs." + concatStringsSep "." example else example);
+      };
 
   /* This option accepts anything, but it does not produce any result.