From b0173716f6b27b4fb307ac9ded544e46e712ad22 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Wed, 19 Jul 2023 15:07:07 +0200
Subject: [PATCH] clarify wording on args@ default handling (#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 <roberth@users.noreply.github.com>
Co-authored-by: John Ericson <git@JohnEricson.me>
---
 doc/manual/src/language/constructs.md | 45 +++++++++++++++++----------
 1 file changed, 28 insertions(+), 17 deletions(-)

diff --git a/doc/manual/src/language/constructs.md b/doc/manual/src/language/constructs.md
index 2482f2d17..a3590f55d 100644
--- 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.,