From 529271e0beb445894300b2be88b6127ba77145c3 Mon Sep 17 00:00:00 2001
From: James Bardin <j.bardin@gmail.com>
Date: Wed, 5 Feb 2020 13:45:49 -0500
Subject: [PATCH] update merge docs to match behavior

---
 lang/funcs/collection_test.go                 |  4 +--
 .../configuration/functions/merge.html.md     | 29 ++++++++++++++-----
 2 files changed, 23 insertions(+), 10 deletions(-)

diff --git a/lang/funcs/collection_test.go b/lang/funcs/collection_test.go
index 552cccfb7d..4e437ab4d8 100644
--- a/lang/funcs/collection_test.go
+++ b/lang/funcs/collection_test.go
@@ -2119,9 +2119,7 @@ func TestMerge(t *testing.T) {
 					"a": cty.List(cty.String),
 				})),
 			},
-			cty.MapVal(map[string]cty.Value{
-				"c": cty.StringVal("d"),
-			}),
+			cty.NullVal(cty.EmptyObject),
 			false,
 		},
 		{ // handle null object
diff --git a/website/docs/configuration/functions/merge.html.md b/website/docs/configuration/functions/merge.html.md
index 162e5a4d24..df9070fb89 100644
--- a/website/docs/configuration/functions/merge.html.md
+++ b/website/docs/configuration/functions/merge.html.md
@@ -3,8 +3,9 @@ layout: "functions"
 page_title: "merge - Functions - Configuration Language"
 sidebar_current: "docs-funcs-collection-merge"
 description: |-
-  The merge function takes an arbitrary number of maps and returns a single
-  map after merging the keys from each argument.
+  The merge function takes an arbitrary number maps or objects, and returns a
+  single map or object that contains a merged set of elements from all
+  arguments.
 ---
 
 # `merge` Function
@@ -13,19 +14,33 @@ description: |-
 earlier, see
 [0.11 Configuration Language: Interpolation Syntax](../../configuration-0-11/interpolation.html).
 
-`merge` takes an arbitrary number of maps and returns a single map that
-contains a merged set of elements from all of the maps.
+`merge` takes an arbitrary number of maps or objects, and returns a single map
+pr object that contains a merged set of elements from all arguments. 
 
-If more than one given map defines the same key then the one that is later
-in the argument sequence takes precedence.
+If more than one given map or object defines the same key or attribute, then
+the one that is later in the argument sequence takes precedence. If the
+argument types do not match, the resulting type will be an object matching the
+type structure of the attributes after the merging rules have been applied.
 
 ## Examples
 
 ```
-> merge({"a"="b", "c"="d"}, {"e"="f", "c"="z"})
+> merge({a="b", c="d"}, {e="f", c="z"})
 {
   "a" = "b"
   "c" = "z"
   "e" = "f"
 }
 ```
+
+```
+> merge({a="b"}, {a=[1,2], c="z"}, {d=3})
+{
+  "a" = [
+    1,
+    2,
+  ]
+  "c" = "z"
+  "d" = 3
+}
+```