lib/options: fix mkPackageOption docs

nixdoc takes everything from Type: to Example: as the type, which
misrendered a large part of the docs. it also drops sorely needed spaces
where the type had line breaks, so all has to be on one line (or use
non-standard literal spaces, which is probably worse).

also clarify what the `?` for arguments mean while we're here.

1 files changed, 5 insertions, 7 deletions

diff --git a/lib/options.nix b/lib/options.nix
index 20e8fb8d5ed31..4780a56fc1c37 100644
--- a/lib/options.nix
+++ b/lib/options.nix
@@ -110,10 +110,6 @@ rec {
   /* Creates an Option attribute set for an option that specifies the
      package a module should use for some purpose.
 
-     Type: mkPackageOption :: pkgs -> (string|[string]) ->
-      { default? :: [string], example? :: null|string|[string], extraDescription? :: string } ->
-      option
-
      The package is specified in the third argument under `default` as a list of strings
      representing its attribute path in nixpkgs (or another package set).
      Because of this, you need to pass nixpkgs itself (or a subset) as the first argument.
@@ -133,6 +129,8 @@ rec {
 
      If you wish to explicitly provide no default, pass `null` as `default`.
 
+     Type: mkPackageOption :: pkgs -> (string|[string]) -> { default? :: [string], example? :: null|string|[string], extraDescription? :: string } -> option
+
      Example:
        mkPackageOption pkgs "hello" { }
        => { _type = "option"; default = «derivation /nix/store/3r2vg51hlxj3cx5vscp0vkv60bqxkaq0-hello-2.10.drv»; defaultText = { ... }; description = "The hello package to use."; type = { ... }; }
@@ -157,11 +155,11 @@ rec {
       # Name for the package, shown in option description
       name:
       {
-        # The attribute path where the default package is located
+        # The attribute path where the default package is located (may be omitted)
         default ? name,
-        # A string or an attribute path to use as an example
+        # A string or an attribute path to use as an example (may be omitted)
         example ? null,
-        # Additional text to include in the option description
+        # Additional text to include in the option description (may be omitted)
         extraDescription ? "",
       }:
       let