From 3fed68b694200a96e4241967f037738b68f895c5 Mon Sep 17 00:00:00 2001
From: Donny Xia <donnyxia@google.com>
Date: Tue, 3 Nov 2020 13:09:12 -0800
Subject: [PATCH] clarify the comments

---
 kyaml/yaml/fns.go      | 8 +++++++-
 kyaml/yaml/fns_test.go | 9 +++++----
 2 files changed, 12 insertions(+), 5 deletions(-)

diff --git a/kyaml/yaml/fns.go b/kyaml/yaml/fns.go
index 45b107618..ad69d3bef 100644
--- a/kyaml/yaml/fns.go
+++ b/kyaml/yaml/fns.go
@@ -41,8 +41,14 @@ func (a ElementAppender) Filter(rn *RNode) (*RNode, error) {
 	return nil, nil
 }
 
-// ElementSetter sets the value for an Element in an associative list.  ElementSetter
+// ElementSetter sets the value for an Element in an associative list. ElementSetter
 // will remove any elements which are empty.
+// ElementSetter will append, replace or delete an element in an associative list.
+// To append, user a key-value pair that doesn't exist in the sequence. Note: this
+// behavior is intended to handle the case that not matching element found. It's
+// not designed for this purpose. To append an element, please use ElementAppender.
+// To replace, set the key-value pair and a non-nil Element.
+// To delete, set the key-value pair and leave the Element as nil.
 type ElementSetter struct {
 	Kind string `yaml:"kind,omitempty"`
 
diff --git a/kyaml/yaml/fns_test.go b/kyaml/yaml/fns_test.go
index 046e6e370..dc6ae3d25 100644
--- a/kyaml/yaml/fns_test.go
+++ b/kyaml/yaml/fns_test.go
@@ -108,7 +108,7 @@ func TestElementSetter(t *testing.T) {
 
 	// ElementSetter will update node, so make a copy
 	node := orig.Copy()
-	// Remove an element
+	// Remove an element, because ElementSetter.Element is left nil.
 	rn, err := node.Pipe(ElementSetter{Key: "a", Value: "b"})
 	assert.NoError(t, err)
 	assert.Nil(t, rn)
@@ -117,7 +117,7 @@ func TestElementSetter(t *testing.T) {
 `, assertNoErrorString(t)(node.String()))
 
 	node = orig.Copy()
-	// Set an element
+	// Set an element, replacing 'a: b' with 'e: f'
 	newElement := NewMapRNode(&map[string]string{
 		"e": "f",
 	})
@@ -134,7 +134,7 @@ func TestElementSetter(t *testing.T) {
 `, assertNoErrorString(t)(node.String()))
 
 	node = orig.Copy()
-	// Set an element with scalar
+	// Set an element with scalar, {"a": "b"} to "foo"
 	newElement = NewScalarRNode("foo")
 	rn, err = node.Pipe(ElementSetter{
 		Key:     "a",
@@ -149,7 +149,8 @@ func TestElementSetter(t *testing.T) {
 `, assertNoErrorString(t)(node.String()))
 
 	node = orig.Copy()
-	// Append an element
+	// Append an element, {"x": "y"} is not in the list
+	// so the element will be appended.
 	newElement = NewMapRNode(&map[string]string{
 		"e": "f",
 	})