lib/options: Update documentation comments for docs generation

Documents functions in `lib.options` for docs generation with nixdoc.

The formatting change in the `mkOption` arguments is due to the way
`nixdoc` parses documentation comments on pattern arguments. It's not
ideal, but it works.

1 files changed, 88 insertions, 67 deletions

diff --git a/lib/options.nix b/lib/options.nix
index 0e3421175306..791930eafbd0 100644
--- a/lib/options.nix
+++ b/lib/options.nix
@@ -8,61 +8,72 @@ with lib.strings;
 
 rec {
 
-  # Returns true when the given argument is an option
-  #
-  # Examples:
-  #   isOption 1             // => false
-  #   isOption (mkOption {}) // => true
+  /* Returns true when the given argument is an option
+
+     Type: isOption :: a -> bool
+
+     Example:
+       isOption 1             // => false
+       isOption (mkOption {}) // => true
+  */
   isOption = lib.isType "option";
 
-  # Creates an Option attribute set. mkOption accepts an attribute set with the following keys:
-  #
-  #  default:     Default value used when no definition is given in the configuration.
-  #  defaultText: Textual representation of the default, for in the manual.
-  #  example:     Example value used in the manual.
-  #  description: String describing the option.
-  #  type:        Option type, providing type-checking and value merging.
-  #  apply:       Function that converts the option value to something else.
-  #  internal:    Whether the option is for NixOS developers only.
-  #  visible:     Whether the option shows up in the manual.
-  #  readOnly:    Whether the option can be set only once
-  #  options:     Obsolete, used by types.optionSet.
-  #
-  # All keys default to `null` when not given.
-  #
-  # Examples:
-  #   mkOption { }  // => { _type = "option"; }
-  #   mkOption { defaultText = "foo"; } // => { _type = "option"; defaultText = "foo"; }
+  /* Creates an Option attribute set. mkOption accepts an attribute set with the following keys:
+
+     All keys default to `null` when not given.
+
+     Example:
+       mkOption { }  // => { _type = "option"; }
+       mkOption { defaultText = "foo"; } // => { _type = "option"; defaultText = "foo"; }
+  */
   mkOption =
-    { default ? null # Default value used when no definition is given in the configuration.
-    , defaultText ? null # Textual representation of the default, for in the manual.
-    , example ? null # Example value used in the manual.
-    , description ? null # String describing the option.
-    , relatedPackages ? null # Related packages used in the manual (see `genRelatedPackages` in ../nixos/doc/manual/default.nix).
-    , type ? null # Option type, providing type-checking and value merging.
-    , apply ? null # Function that converts the option value to something else.
-    , internal ? null # Whether the option is for NixOS developers only.
-    , visible ? null # Whether the option shows up in the manual.
-    , readOnly ? null # Whether the option can be set only once
-    , options ? null # Obsolete, used by types.optionSet.
+    {
+    # Default value used when no definition is given in the configuration.
+    default ? null,
+    # Textual representation of the default, for the manual.
+    defaultText ? null,
+    # Example value used in the manual.
+    example ? null,
+    # String describing the option.
+    description ? null,
+    # Related packages used in the manual (see `genRelatedPackages` in ../nixos/doc/manual/default.nix).
+    relatedPackages ? null,
+    # Option type, providing type-checking and value merging.
+    type ? null,
+    # Function that converts the option value to something else.
+    apply ? null,
+    # Whether the option is for NixOS developers only.
+    internal ? null,
+    # Whether the option shows up in the manual.
+    visible ? null,
+    # Whether the option can be set only once
+    readOnly ? null,
+    # Obsolete, used by types.optionSet.
+    options ? null
     } @ attrs:
     attrs // { _type = "option"; };
 
-  # Creates a Option attribute set for a boolean value option i.e an option to be toggled on or off:
-  #
-  # Examples:
-  #   mkEnableOption "foo" // => { _type = "option"; default = false; description = "Whether to enable foo."; example = true; type = { ... }; }
-  mkEnableOption = name: mkOption {
+  /* Creates an Option attribute set for a boolean value option i.e an
+     option to be toggled on or off:
+
+     Example:
+       mkEnableOption "foo"
+       => { _type = "option"; default = false; description = "Whether to enable foo."; example = true; type = { ... }; }
+  */
+  mkEnableOption =
+    # Name for the created option
+    name: mkOption {
     default = false;
     example = true;
     description = "Whether to enable ${name}.";
     type = lib.types.bool;
   };
 
-  # This option accept anything, but it does not produce any result.  This
-  # is useful for sharing a module across different module sets without
-  # having to implement similar features as long as the value of the options
-  # are not expected.
+  /* This option accepts anything, but it does not produce any result.
+
+     This is useful for sharing a module across different module sets
+     without having to implement similar features as long as the
+     values of the options are not accessed. */
   mkSinkUndeclaredOptions = attrs: mkOption ({
     internal = true;
     visible = false;
@@ -102,18 +113,24 @@ rec {
       else
         val) (head defs).value defs;
 
-  # Extracts values of all "value" keys of the given list
-  #
-  # Examples:
-  #   getValues [ { value = 1; } { value = 2; } ] // => [ 1 2 ]
-  #   getValues [ ]                               // => [ ]
+  /* Extracts values of all "value" keys of the given list.
+
+     Type: getValues :: [ { value :: a } ] -> [a]
+
+     Example:
+       getValues [ { value = 1; } { value = 2; } ] // => [ 1 2 ]
+       getValues [ ]                               // => [ ]
+  */
   getValues = map (x: x.value);
 
-  # Extracts values of all "file" keys of the given list
-  #
-  # Examples:
-  #   getFiles [ { file = "file1"; } { file = "file2"; } ] // => [ "file1" "file2" ]
-  #   getFiles [ ]                                         // => [ ]
+  /* Extracts values of all "file" keys of the given list
+
+     Type: getFiles :: [ { file :: a } ] -> [a]
+
+     Example:
+       getFiles [ { file = "file1"; } { file = "file2"; } ] // => [ "file1" "file2" ]
+       getFiles [ ]                                         // => [ ]
+  */
   getFiles = map (x: x.file);
 
   # Generate documentation template from the list of option declaration like
@@ -146,10 +163,13 @@ rec {
 
 
   /* This function recursively removes all derivation attributes from
-     `x' except for the `name' attribute.  This is to make the
-     generation of `options.xml' much more efficient: the XML
-     representation of derivations is very large (on the order of
-     megabytes) and is not actually used by the manual generator. */
+     `x` except for the `name` attribute.
+
+     This is to make the generation of `options.xml` much more
+     efficient: the XML representation of derivations is very large
+     (on the order of megabytes) and is not actually used by the
+     manual generator.
+  */
   scrubOptionValue = x:
     if isDerivation x then
       { type = "derivation"; drvPath = x.name; outPath = x.name; name = x.name; }
@@ -158,20 +178,21 @@ rec {
     else x;
 
 
-  /* For use in the ‘example’ option attribute.  It causes the given
-     text to be included verbatim in documentation.  This is necessary
-     for example values that are not simple values, e.g.,
-     functions. */
+  /* For use in the `example` option attribute. It causes the given
+     text to be included verbatim in documentation. This is necessary
+     for example values that are not simple values, e.g., functions.
+  */
   literalExample = text: { _type = "literalExample"; inherit text; };
 
+  # Helper functions.
 
-  /* Helper functions. */
+  /* Convert an option, described as a list of the option parts in to a
+     safe, human readable version.
 
-  # Convert an option, described as a list of the option parts in to a
-  # safe, human readable version. ie:
-  #
-  # (showOption ["foo" "bar" "baz"]) == "foo.bar.baz"
-  # (showOption ["foo" "bar.baz" "tux"]) == "foo.\"bar.baz\".tux"
+     Example:
+       (showOption ["foo" "bar" "baz"]) == "foo.bar.baz"
+       (showOption ["foo" "bar.baz" "tux"]) == "foo.\"bar.baz\".tux"
+  */
   showOption = parts: let
     escapeOptionPart = part:
       let