From 3dd5f0c80c73105a50afe7898b0dd2e4744d156c Mon Sep 17 00:00:00 2001
From: Mike Farah <mikefarah@gmail.com>
Date: Fri, 30 Sep 2022 10:15:41 +1000
Subject: [PATCH] Added another comment test

---
 pkg/yqlib/doc/operators/comment-operators.md  | 21 ++++++++++++++++++-
 .../operators/headers/comment-operators.md    |  2 +-
 pkg/yqlib/operator_comments_test.go           |  8 +++++++
 3 files changed, 29 insertions(+), 2 deletions(-)

diff --git a/pkg/yqlib/doc/operators/comment-operators.md b/pkg/yqlib/doc/operators/comment-operators.md
index d29a9b19..0cbc547a 100644
--- a/pkg/yqlib/doc/operators/comment-operators.md
+++ b/pkg/yqlib/doc/operators/comment-operators.md
@@ -1,6 +1,6 @@
 # Comment Operators
 
-Use these comment operators to set or retrieve comments.
+Use these comment operators to set or retrieve comments. Note that line comments on maps/arrays are actually set on the _key_ node as opposed to the _value_ (map/array). See below for examples.
 
 Like the `=` and `|=` assign operators, the same syntax applies when updating comments:
 
@@ -82,6 +82,25 @@ will output
 a: cat
 ```
 
+## Set head comment of a map entry
+Given a sample.yml file of:
+```yaml
+f: foo
+a:
+  b: cat
+```
+then
+```bash
+yq '(.a | key) head_comment="single"' sample.yml
+```
+will output
+```yaml
+f: foo
+# single
+a:
+  b: cat
+```
+
 ## Set foot comment, using an expression
 Given a sample.yml file of:
 ```yaml
diff --git a/pkg/yqlib/doc/operators/headers/comment-operators.md b/pkg/yqlib/doc/operators/headers/comment-operators.md
index 3d5f2703..d7a19d2c 100644
--- a/pkg/yqlib/doc/operators/headers/comment-operators.md
+++ b/pkg/yqlib/doc/operators/headers/comment-operators.md
@@ -1,6 +1,6 @@
 # Comment Operators
 
-Use these comment operators to set or retrieve comments.
+Use these comment operators to set or retrieve comments. Note that line comments on maps/arrays are actually set on the _key_ node as opposed to the _value_ (map/array). See below for examples.
 
 Like the `=` and `|=` assign operators, the same syntax applies when updating comments:
 
diff --git a/pkg/yqlib/operator_comments_test.go b/pkg/yqlib/operator_comments_test.go
index c5c3cfb6..8c6f1238 100644
--- a/pkg/yqlib/operator_comments_test.go
+++ b/pkg/yqlib/operator_comments_test.go
@@ -64,6 +64,14 @@ var commentOperatorScenarios = []expressionScenario{
 			"D0, P[], (doc)::# single\n\na: cat\n",
 		},
 	},
+	{
+		description: "Set head comment of a map entry",
+		document:    "f: foo\na:\n  b: cat",
+		expression:  `(.a | key) head_comment="single"`,
+		expected: []string{
+			"D0, P[], (doc)::f: foo\n# single\na:\n    b: cat\n",
+		},
+	},
 	{
 		description: "Set foot comment, using an expression",
 		document:    `a: cat`,