Merge pull request #11305 from NixOS/doc-apply

Document function application operator

doc/manual/src/language/operators.md

@@ -3,7 +3,7 @@
 | Name                                   | Syntax                                     | Associativity | Precedence |
 |----------------------------------------|--------------------------------------------|---------------|------------|
 | [Attribute selection]                  | *attrset* `.` *attrpath* \[ `or` *expr* \] | none          | 1          |
-| Function application                   | *func* *expr*                              | left          | 2          |
+| [Function application]                 | *func* *expr*                              | left          | 2          |
 | [Arithmetic negation][arithmetic]      | `-` *number*                               | none          | 3          |
 | [Has attribute]                        | *attrset* `?` *attrpath*                   | none          | 4          |
 | List concatenation                     | *list* `++` *list*                         | right         | 5          |
@@ -32,7 +32,7 @@
 [string]: ./types.md#type-string
 [path]: ./types.md#type-path
 [number]: ./types.md#type-float
-[list]: ./types.md#list
+[list]: ./types.md#type-list
 [attribute set]: ./types.md#attribute-set
 
 <!-- TODO(@rhendric, #10970): ^ rationalize number -> int/float -->
@@ -48,6 +48,22 @@ If the attribute doesn’t exist, return the *expr* after `or` if provided, othe
 
 [Attribute selection]: #attribute-selection
 
+## Function application
+
+> **Syntax**
+>
+> *func* *expr*
+
+Apply the callable value *func* to the argument *expr*. Note the absence of any visible operator symbol.
+A callable value is either:
+- a [user-defined function][function]
+- a [built-in][builtins] function
+- an attribute set with a [`__functor` attribute](./syntax.md#attr-__functor)
+
+> **Warning**
+>
+> [List][list] items are also separated by whitespace, which means that function calls in list items must be enclosed by parentheses.
+
 ## Has attribute
 
 > **Syntax**
@@ -215,3 +231,5 @@ Equivalent to `!`*b1* `||` *b2*.
 > ```
 
 [Pipe operator]: #pipe-operators
+[builtins]: ./builtins.md
+[Function application]: #function-application

doc/manual/src/language/syntax.md

@@ -218,7 +218,7 @@ a string), that attribute is simply not added to the set:
 
 This will evaluate to `{}` if `foo` evaluates to `false`.
 
-A set that has a `__functor` attribute whose value is callable (i.e. is
+A set that has a [`__functor`]{#attr-__functor} attribute whose value is callable (i.e. is
 itself a function or a set with a `__functor` attribute whose value is
 callable) can be applied as if it were a function, with the set itself
 passed in first , e.g.,