From 877a47cb19475f1a1f764b2c9514813fb006f95d Mon Sep 17 00:00:00 2001
From: Mike Farah <mikefarah@gmail.com>
Date: Fri, 19 Sep 2025 14:59:19 +1000
Subject: [PATCH] Improving first op docs

---
 pkg/yqlib/doc/operators/first.md | 43 ++------------------------------
 pkg/yqlib/operator_first_test.go | 14 ++++++-----
 2 files changed, 10 insertions(+), 47 deletions(-)

diff --git a/pkg/yqlib/doc/operators/first.md b/pkg/yqlib/doc/operators/first.md
index 65599092..349fe1b0 100644
--- a/pkg/yqlib/doc/operators/first.md
+++ b/pkg/yqlib/doc/operators/first.md
@@ -273,7 +273,7 @@ will output
 100
 ```
 
-## First element with no RHS from array
+## First element with no filter from array
 Given a sample.yml file of:
 ```yaml
 - 10
@@ -289,7 +289,7 @@ will output
 10
 ```
 
-## First element with no RHS from array of maps
+## First element with no filter from array of maps
 Given a sample.yml file of:
 ```yaml
 - a: 10
@@ -304,42 +304,3 @@ will output
 a: 10
 ```
 
-## No RHS on empty array returns nothing
-Given a sample.yml file of:
-```yaml
-[]
-```
-then
-```bash
-yq 'first' sample.yml
-```
-will output
-```yaml
-```
-
-## No RHS on scalar returns nothing
-Given a sample.yml file of:
-```yaml
-hello
-```
-then
-```bash
-yq 'first' sample.yml
-```
-will output
-```yaml
-```
-
-## No RHS on null returns nothing
-Given a sample.yml file of:
-```yaml
-null
-```
-then
-```bash
-yq 'first' sample.yml
-```
-will output
-```yaml
-```
-
diff --git a/pkg/yqlib/operator_first_test.go b/pkg/yqlib/operator_first_test.go
index 3805b17f..44ad9c0e 100644
--- a/pkg/yqlib/operator_first_test.go
+++ b/pkg/yqlib/operator_first_test.go
@@ -139,9 +139,8 @@ var firstOperatorScenarios = []expressionScenario{
 			"D0, P[1], (!!int)::100\n",
 		},
 	},
-	// New tests for no RHS (return first child)
 	{
-		description: "First element with no RHS from array",
+		description: "First element with no filter from array",
 		document:    "[10, 100, 1]",
 		expression:  `first`,
 		expected: []string{
@@ -149,7 +148,7 @@ var firstOperatorScenarios = []expressionScenario{
 		},
 	},
 	{
-		description: "First element with no RHS from array of maps",
+		description: "First element with no filter from array of maps",
 		document:    "[{a: 10},{a: 100}]",
 		expression:  `first`,
 		expected: []string{
@@ -157,19 +156,22 @@ var firstOperatorScenarios = []expressionScenario{
 		},
 	},
 	{
-		description: "No RHS on empty array returns nothing",
+		description: "No filter on empty array returns nothing",
+		skipDoc:     true,
 		document:    "[]",
 		expression:  `first`,
 		expected:    []string{},
 	},
 	{
-		description: "No RHS on scalar returns nothing",
+		description: "No filter on scalar returns nothing",
+		skipDoc:     true,
 		document:    "hello",
 		expression:  `first`,
 		expected:    []string{},
 	},
 	{
-		description: "No RHS on null returns nothing",
+		description: "No filter on null returns nothing",
+		skipDoc:     true,
 		document:    "null",
 		expression:  `first`,
 		expected:    []string{},