clarify wording on args@ default handling (NixOS#8596)

* clarify wording on args@ default handling Most importantly use shorter sentences and emphasize the key point that defaults aren't taken into account Co-authored-by: Robert Hensing <[email protected]> Co-authored-by: John Ericson <[email protected]>
ryantm · Jul 19, 2023 · b017371 · b017371
1 parent 32494cb
commit b017371
Showing 1 changed file with 28 additions and 17 deletions.
diff --git a/doc/manual/src/language/constructs.md b/doc/manual/src/language/constructs.md
@@ -208,30 +208,41 @@ three kinds of patterns:
     ```nix
     { x, y, z, ... } @ args: z + y + x + args.a
     ```
-    
-    Here `args` is bound to the entire argument, which is further
-    matched against the pattern `{ x, y, z,
-            ... }`. `@`-pattern makes mainly sense with an ellipsis(`...`) as
+
+    Here `args` is bound to the argument *as passed*, which is further
+    matched against the pattern `{ x, y, z, ... }`.
+    The `@`-pattern makes mainly sense with an ellipsis(`...`) as
     you can access attribute names as `a`, using `args.a`, which was
     given as an additional attribute to the function.
-    
+
     > **Warning**
-    > 
-    > The `args@` expression is bound to the argument passed to the
-    > function which means that attributes with defaults that aren't
-    > explicitly specified in the function call won't cause an
-    > evaluation error, but won't exist in `args`.
-    > 
+    >
+    > `args@` binds the name `args` to the attribute set that is passed to the function.
+    > In particular, `args` does *not* include any default values specified with `?` in the function's set pattern.
+    >
     > For instance
-    > 
+    >
     > ```nix
     > let
-    >   function = args@{ a ? 23, ... }: args;
+    >   f = args@{ a ? 23, ... }: [ a args ];
     > in
-    >   function {}
-    > ````
-    > 
-    > will evaluate to an empty attribute set.
+    >   f {}
+    > ```
+    >
+    > is equivalent to
+    >
+    > ```nix
+    > let
+    >   f = args @ { ... }: [ (args.a or 23) args ];
+    > in
+    >   f {}
+    > ```
+    >
+    > and both expressions will evaluate to:
+    >
+    > ```nix
+    > [ 23 {} ]
+    > ```
 
 Note that functions do not have names. If you want to give them a name,
 you can bind them to an attribute, e.g.,