From a3f148ce96493fa320a947e7a134b417880ee987 Mon Sep 17 00:00:00 2001
From: Marc Weber <marco-oweber@gmx.de>
Date: Thu, 22 Aug 2013 10:01:27 +0300
Subject: [PATCH] Improve option types documentation.

---
 pkgs/lib/types.nix | 19 ++++++++++++++++---
 1 file changed, 16 insertions(+), 3 deletions(-)

diff --git a/pkgs/lib/types.nix b/pkgs/lib/types.nix
index f9a195a80ba3..b634cccc8c69 100644
--- a/pkgs/lib/types.nix
+++ b/pkgs/lib/types.nix
@@ -19,7 +19,7 @@ rec {
 
 
   # name (name of the type)
-  # check (boolean function)
+  # check (check the config value. Before returning false it should trace the bad value eg using traceValIfNot)
   # merge (default merge function)
   # iter (iterate on all elements contained in this type)
   # fold (fold all elements contained in this type)
@@ -196,8 +196,21 @@ rec {
       hasOptions = false;
     };
 
-    # !!! this should be a type constructor that takes the options as
-    # an argument.
+    # usually used with listOf, attrsOf, loaOf like this:
+    # users = mkOption {
+    #   type = loaOf optionSet;
+    #
+    #   # you can omit the list if there is one element only
+    #   options = [ {
+    #     name = mkOption {
+    #       description = "name of the user"
+    #       ...
+    #     };
+    #     # more options here
+    #   } { more options } ];
+    # }
+    # TODO: !!! document passing options as an argument to optionSet,
+    # deprecate the current approach.
     optionSet = mkOptionType {
       name = "option set";
       # merge is done in "options.nix > addOptionMakeUp > handleOptionSets"