Update merge function examples (#1662)

Supersedes #1641
Closes #1641

content/en/functions/merge.md

@@ -1,6 +1,6 @@
 ---
 title: merge
-description: "`merge` deep merges two maps and returns the resulting map."
+description: "Returns the result of merging two or more maps."
 date: 2019-08-08
 categories: [functions]
 menu:
@@ -14,28 +14,58 @@ relatedfuncs: [dict, append, reflect.IsMap, reflect.IsSlice]
 aliases: []
 ---
 
-Merge creates a copy of the final `MAP` and merges any preceding `MAP` into it in reverse order.
+Returns the result of merging two or more maps from left to right. If a key already exists, `merge` updates its value. If a key is absent, `merge` inserts the value under the new key.
+
 Key handling is case-insensitive.
 
-An example merging two maps.
+The following examples use these map definitions:
 
 ```go-html-template
-{{ $default_params := dict "color" "blue" "width" "50%" "height" "25%" "icon" "star" }}
+{{ $m1 := dict "x" "foo" }}
-{{ $user_params := dict "color" "red" "icon" "mail" "extra" (dict "duration" 2) }}
+{{ $m2 := dict "x" "bar" "y" "wibble" }}
-{{ $params := merge $default_params $user_params }}
+{{ $m3 := dict "x" "baz" "y" "wobble" "z" (dict "a" "huey") }}
 ```
 
-Resulting __$params__:
+Example 1
 
+```go-html-template
+{{ $merged := merge $m1 $m2 $m3 }}
+
+{{ $merged.x }}   --> baz
+{{ $merged.y }}   --> wobble
+{{ $merged.z.a }} --> huey
 ```
-"color": "red"
+
-"extra":
+Example 2
-  "duration": 2
+
-"height": "25%"
+```go-html-template
-"icon": "mail"
+{{ $merged := merge $m3 $m2 $m1 }}
-"width": "50%"
+
+{{ $merged.x }}   --> foo
+{{ $merged.y }}   --> wibble
+{{ $merged.z.a }} --> huey
+```
+
+Example 3
+
+```go-html-template
+{{ $merged := merge $m2 $m3 $m1 }}
+
+{{ $merged.x }}   --> foo
+{{ $merged.y }}   --> wobble
+{{ $merged.z.a }} --> huey
+```
+
+Example 4
+
+```go-html-template
+{{ $merged := merge $m1 $m3 $m2 }}
+
+{{ $merged.x }}   --> bar
+{{ $merged.y }}   --> wibble
+{{ $merged.z.a }} --> huey
 ```
 
 {{% note %}}
-  Regardless of depth, merging only applies to maps. For slices, use [append]({{< ref "functions/append" >}})
+Regardless of depth, merging only applies to maps. For slices, use [append]({{< ref "functions/append" >}}).
 {{% /note %}}