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`,