From be304a1102793e5d064c384f1e1d0c7ed0572762 Mon Sep 17 00:00:00 2001
From: Mike Farah <mikefarah@gmail.com>
Date: Fri, 30 Sep 2022 09:46:07 +1000
Subject: [PATCH] Added another comment test

---
 examples/data1.yaml                          | 17 +++++------------
 pkg/yqlib/doc/operators/comment-operators.md | 20 ++++++++++++++++++++
 pkg/yqlib/operator_comments_test.go          | 16 +++++++++++++---
 3 files changed, 38 insertions(+), 15 deletions(-)

diff --git a/examples/data1.yaml b/examples/data1.yaml
index 8c193829..f1011d30 100644
--- a/examples/data1.yaml
+++ b/examples/data1.yaml
@@ -1,12 +1,5 @@
-# --------------------------------------------------
-# It's a test with comment
-# --------------------------------------------------
-test:
-  - name: a
-  - name: b
-  - name: c
-groups:
-  - name: a
-  - name: b
-  - name: c
-  - name: c
\ No newline at end of file
+volumes:
+  beehive-conf:
+    driver: local
+services:
+  - beehive
\ No newline at end of file
diff --git a/pkg/yqlib/doc/operators/comment-operators.md b/pkg/yqlib/doc/operators/comment-operators.md
index e53c3fc5..d29a9b19 100644
--- a/pkg/yqlib/doc/operators/comment-operators.md
+++ b/pkg/yqlib/doc/operators/comment-operators.md
@@ -17,6 +17,8 @@ Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#
 {% endhint %}
 
 ## Set line comment
+Set the comment on the key node for more reliability (see below).
+
 Given a sample.yml file of:
 ```yaml
 a: cat
@@ -30,6 +32,24 @@ will output
 a: cat # single
 ```
 
+## Set line comment of a maps/arrays
+For maps and arrays, you need to set the line comment on the _key_ node. This will also work for scalars.
+
+Given a sample.yml file of:
+```yaml
+a:
+  b: things
+```
+then
+```bash
+yq '(.a | key) line_comment="single"' sample.yml
+```
+will output
+```yaml
+a: # single
+  b: things
+```
+
 ## Use update assign to perform relative updates
 Given a sample.yml file of:
 ```yaml
diff --git a/pkg/yqlib/operator_comments_test.go b/pkg/yqlib/operator_comments_test.go
index 65effab9..c5c3cfb6 100644
--- a/pkg/yqlib/operator_comments_test.go
+++ b/pkg/yqlib/operator_comments_test.go
@@ -6,13 +6,23 @@ import (
 
 var commentOperatorScenarios = []expressionScenario{
 	{
-		description: "Set line comment",
-		document:    `a: cat`,
-		expression:  `.a line_comment="single"`,
+		description:    "Set line comment",
+		subdescription: "Set the comment on the key node for more reliability (see below).",
+		document:       `a: cat`,
+		expression:     `.a line_comment="single"`,
 		expected: []string{
 			"D0, P[], (doc)::a: cat # single\n",
 		},
 	},
+	{
+		description:    "Set line comment of a maps/arrays",
+		subdescription: "For maps and arrays, you need to set the line comment on the _key_ node. This will also work for scalars.",
+		document:       "a:\n  b: things",
+		expression:     `(.a | key) line_comment="single"`,
+		expected: []string{
+			"D0, P[], (doc)::a: # single\n    b: things\n",
+		},
+	},
 	{
 		skipDoc:    true,
 		document:   "a: cat\nb: dog",