Merge pull request #207227 from hsjobeki/docs/fix-attrsets

Docs/fix attrsets

lib/attrsets.nix

···
 
      Example:
        x = { a = { b = 3; }; }
+       # ["a" "b"] is equivalent to x.a.b
+       # 6 is a default value to return if the path does not exist in attrset
        attrByPath ["a" "b"] 6 x
        => 3
        attrByPath ["z" "z"] 6 x
···
 
      Type:
        attrByPath :: [String] -> Any -> AttrSet -> Any
+
   */
   attrByPath =
     # A list of strings representing the attribute path to return from `set`
···
        => error: cannot find attribute `z.z'
 
      Type:
-       getAttrFromPath :: [String] -> AttrSet -> Value
+       getAttrFromPath :: [String] -> AttrSet -> Any
   */
   getAttrFromPath =
     # A list of strings representing the attribute path to get from `set`
···
   /* Map each attribute in the given set and merge them into a new attribute set.
 
      Type:
-       concatMapAttrs ::
-         (String -> a -> AttrSet)
-         -> AttrSet
-         -> AttrSet
+       concatMapAttrs :: (String -> a -> AttrSet) -> AttrSet -> AttrSet
 
      Example:
        concatMapAttrs
···
        ] { a.b.c = 0; }
        => { a = { b = { d = 1; }; }; x = { y = "xy"; }; }
 
-    Type:
-      updateManyAttrsByPath :: [AttrSet] -> AttrSet -> AttrSet
+    Type: updateManyAttrsByPath :: [{ path :: [String], update :: (Any -> Any) }] -> AttrSet -> AttrSet
   */
   updateManyAttrsByPath = let
     # When recursing into attributes, instead of updating the `path` of each
···
      Example:
        attrValues {c = 3; a = 1; b = 2;}
        => [1 2 3]
+
      Type:
        attrValues :: AttrSet -> [Any]
   */
···
 
      Type:
        foldAttrs :: (Any -> Any -> Any) -> Any -> [AttrSets] -> Any
+
   */
   foldAttrs =
     # A function, given a value and a collector combines the two.
···
            { a = 2; b = 20; }
          ]
      Type:
-     cartesianProductOfSets :: AttrSet -> [AttrSet]
+       cartesianProductOfSets :: AttrSet -> [AttrSet]
   */
   cartesianProductOfSets =
     # Attribute set with attributes that are lists of values
···
        => { name = "some"; value = 6; }
 
      Type:
-       nameValuePair :: String -> Any -> AttrSet
+       nameValuePair :: String -> Any -> { name :: String, value :: Any }
   */
   nameValuePair =
     # Attribute name
···
        => { }
 
      Type:
-       optionalAttrs :: Bool -> AttrSet
+       optionalAttrs :: Bool -> AttrSet -> AttrSet
   */
   optionalAttrs =
     # Condition under which the `as` attribute set is returned.
···
        => { a = ["x" "y"]; b = ["z"] }
 
      Type:
-     zipAttrsWith :: (String -> [ Any ] -> Any) -> [ AttrSet ] -> AttrSet
+       zipAttrsWith :: (String -> [ Any ] -> Any) -> [ AttrSet ] -> AttrSet
   */
   zipAttrsWith =
     builtins.zipAttrsWith or (f: sets: zipAttrsWithNames (concatMap attrNames sets) f sets);
···
        }
 
      Type:
-     recursiveUpdate :: AttrSet -> AttrSet -> AttrSet
+       recursiveUpdate :: AttrSet -> AttrSet -> AttrSet
   */
   recursiveUpdate =
     # Left attribute set of the merge.
···
   /* Turns a list of strings into a human-readable description of those
     strings represented as an attribute path. The result of this function is
     not intended to be machine-readable.
+    Create a new attribute set with `value` set at the nested attribute location specified in `attrPath`.
 
     Example:
       showAttrPath [ "foo" "10" "bar" ]
···
      If the output does not exist, fallback to `.out` and then to the default.
 
      Example:
-       getOutput pkgs.openssl
+       getBin pkgs.openssl
        => "/nix/store/9rz8gxhzf8sw4kf2j2f1grr49w8zx5vj-openssl-1.0.1r"
 
      Type:
-       getOutput :: Derivation -> String
+       getBin :: Derivation -> String
   */
   getBin = getOutput "bin";
 
···
      If the output does not exist, fallback to `.out` and then to the default.
 
      Example:
-       getOutput pkgs.openssl
+       getLib pkgs.openssl
        => "/nix/store/9rz8gxhzf8sw4kf2j2f1grr49w8zx5vj-openssl-1.0.1r-lib"
 
      Type:
-       getOutput :: Derivation -> String
+       getLib :: Derivation -> String
   */
   getLib = getOutput "lib";
 
···
      If the output does not exist, fallback to `.out` and then to the default.
 
      Example:
-       getOutput pkgs.openssl
+       getDev pkgs.openssl
        => "/nix/store/9rz8gxhzf8sw4kf2j2f1grr49w8zx5vj-openssl-1.0.1r-dev"
 
      Type:
-       getOutput :: Derivation -> String
+       getDev :: Derivation -> String
   */
   getDev = getOutput "dev";
 
···
      If the output does not exist, fallback to `.out` and then to the default.
 
      Example:
-       getOutput pkgs.openssl
+       getMan pkgs.openssl
        => "/nix/store/9rz8gxhzf8sw4kf2j2f1grr49w8zx5vj-openssl-1.0.1r-man"
 
      Type:
-       getOutput :: Derivation -> String
+       getMan :: Derivation -> String
   */
   getMan = getOutput "man";
 
-  /* Pick the outputs of packages to place in `buildInputs` */
+  /* Pick the outputs of packages to place in `buildInputs`
+
+   Type: chooseDevOutputs :: [Derivation] -> [String]
+
+  */
   chooseDevOutputs =
     # List of packages to pick `dev` outputs from
     drvs:
···
 
      Type:
        recurseIntoAttrs :: AttrSet -> AttrSet
+
    */
   recurseIntoAttrs =
     # An attribute set to scan for derivations.
···
   /* Undo the effect of recurseIntoAttrs.
 
      Type:
-       recurseIntoAttrs :: AttrSet -> AttrSet
+       dontRecurseIntoAttrs :: AttrSet -> AttrSet
    */
   dontRecurseIntoAttrs =
     # An attribute set to not scan for derivations.
···
   /* `unionOfDisjoint x y` is equal to `x // y // z` where the
      attrnames in `z` are the intersection of the attrnames in `x` and
      `y`, and all values `assert` with an error message.  This
-      operator is commutative, unlike (//). */
+      operator is commutative, unlike (//).
+
+     Type: unionOfDisjoint :: AttrSet -> AttrSet -> AttrSet
+  */
   unionOfDisjoint = x: y:
     let
       intersection = builtins.intersectAttrs x y;
···
     in
       (x // y) // mask;
 
-  # deprecated
+  # DEPRECATED
   zipWithNames = zipAttrsWithNames;
-  # deprecated
+
+  # DEPRECATED
   zip = builtins.trace
     "lib.zip is deprecated, use lib.zipAttrsWith instead" zipAttrsWith;
 }

lib/options.nix

···
   /* Creates an Option attribute set for an option that specifies the
      package a module should use for some purpose.
 
-     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.
···
      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.
+
+     Type: mkPackageOption :: pkgs -> string -> { default :: [string], example :: null | string | [string] } -> option
 
      Example:
        mkPackageOption pkgs "hello" { }