Updating with documentation

pkg/yqlib/doc/With.md

@@ -1,4 +1,4 @@
-Use the `with` operator to conveniently make multiple updates to a deeply nested path, or to update array elements relatively to each other.
+Use the `with` operator to conveniently make multiple updates to a deeply nested path, or to update array elements relatively to each other. The first argument expression sets the root context, and the second expression runs against that root context.
 
 ## Update and style
 Given a sample.yml file of:
@@ -39,6 +39,8 @@ a:
 ```
 
 ## Update array elements relatively
+The second expression runs with each element of the array as it's contextual root. This allows you to make updates relative to the element.
+
 Given a sample.yml file of:
 ```yaml
 myArray:

pkg/yqlib/doc/headers/With.md

@@ -1 +1 @@
-Use the `with` operator to conveniently make multiple updates to a deeply nested path, or to update array elements relatively to each other.
+Use the `with` operator to conveniently make multiple updates to a deeply nested path, or to update array elements relatively to each other. The first argument expression sets the root context, and the second expression runs against that root context.

pkg/yqlib/operator_with_test.go

@@ -20,9 +20,10 @@ var withOperatorScenarios = []expressionScenario{
 		},
 	},
 	{
-		description: "Update array elements relatively",
-		document:    `myArray: [{a: apple},{a: banana}]`,
-		expression:  `with(.myArray[]; .b = .a + " yum")`,
+		description:    "Update array elements relatively",
+		subdescription: "The second expression runs with each element of the array as it's contextual root. This allows you to make updates relative to the element.",
+		document:       `myArray: [{a: apple},{a: banana}]`,
+		expression:     `with(.myArray[]; .b = .a + " yum")`,
 		expected: []string{
 			"D0, P[], (doc)::myArray: [{a: apple, b: apple yum}, {a: banana, b: banana yum}]\n",
 		},