Fixed test doc gen

Author: mikefarah

pkg/yqlib/doc/operators/anchor-and-alias-operators.md

@@ -14,7 +14,7 @@ This flag also enables advanced merging, like inline maps, as well as fixes to e
 
 Long story short, you should be setting this flag to true.
 
-See examples of the flag differences below.
+See examples of the flag differences below, where LEGACY is with the flag off; and FIXED is with the flag on.
 
 
 ## Merge one map

pkg/yqlib/doc/operators/headers/anchor-and-alias-operators.md

@@ -14,5 +14,5 @@ This flag also enables advanced merging, like inline maps, as well as fixes to e
 
 Long story short, you should be setting this flag to true.
 
-See examples of the flag differences below.
+See examples of the flag differences below, where LEGACY is with the flag off; and FIXED is with the flag on.
 

pkg/yqlib/doc/operators/headers/traverse-read.md

@@ -8,5 +8,5 @@ This is the simplest (and perhaps most used) operator. It is used to navigate de
 
 To minimise disruption while still fixing the issue, a flag has been added to toggle this behaviour. This will first default to false; and log warnings to users. Then it will default to true (and still allow users to specify false if needed)
 
-See examples of the flag differences below.
+See examples of the flag differences below, where LEGACY is the flag off; and FIXED is with the flag on.
 

pkg/yqlib/doc/operators/traverse-read.md

@@ -8,7 +8,7 @@ This is the simplest (and perhaps most used) operator. It is used to navigate de
 
 To minimise disruption while still fixing the issue, a flag has been added to toggle this behaviour. This will first default to false; and log warnings to users. Then it will default to true (and still allow users to specify false if needed)
 
-See examples of the flag differences below.
+See examples of the flag differences below, where LEGACY is the flag off; and FIXED is with the flag on.
 
 
 ## Simple map navigation
@@ -498,3 +498,140 @@ bar_thing
 foobarList_c
 ```
 
+## FIXED: Traversing merge anchors with override
+Set `--yaml-fix-merge-anchor-to-spec=true` to get this correct merge behaviour.
+
+Given a sample.yml file of:
+```yaml
+foo: &foo
+  a: foo_a
+  thing: foo_thing
+  c: foo_c
+bar: &bar
+  b: bar_b
+  thing: bar_thing
+  c: bar_c
+foobarList:
+  b: foobarList_b
+  !!merge <<:
+    - *foo
+    - *bar
+  c: foobarList_c
+foobar:
+  c: foobar_c
+  !!merge <<: *foo
+  thing: foobar_thing
+```
+then
+```bash
+yq '.foobar.c' sample.yml
+```
+will output
+```yaml
+foobar_c
+```
+
+## FIXED: Traversing merge anchor lists
+Set `--yaml-fix-merge-anchor-to-spec=true` to get this correct merge behaviour. Note that the keys earlier in the merge anchors sequence override later ones
+
+Given a sample.yml file of:
+```yaml
+foo: &foo
+  a: foo_a
+  thing: foo_thing
+  c: foo_c
+bar: &bar
+  b: bar_b
+  thing: bar_thing
+  c: bar_c
+foobarList:
+  b: foobarList_b
+  !!merge <<:
+    - *foo
+    - *bar
+  c: foobarList_c
+foobar:
+  c: foobar_c
+  !!merge <<: *foo
+  thing: foobar_thing
+```
+then
+```bash
+yq '.foobarList.thing' sample.yml
+```
+will output
+```yaml
+foo_thing
+```
+
+## FIXED: Splatting merge anchors
+Set `--yaml-fix-merge-anchor-to-spec=true` to get this correct merge behaviour. Note that the keys earlier in the merge anchors sequence override later ones
+
+Given a sample.yml file of:
+```yaml
+foo: &foo
+  a: foo_a
+  thing: foo_thing
+  c: foo_c
+bar: &bar
+  b: bar_b
+  thing: bar_thing
+  c: bar_c
+foobarList:
+  b: foobarList_b
+  !!merge <<:
+    - *foo
+    - *bar
+  c: foobarList_c
+foobar:
+  c: foobar_c
+  !!merge <<: *foo
+  thing: foobar_thing
+```
+then
+```bash
+yq '.foobar[]' sample.yml
+```
+will output
+```yaml
+foo_a
+foobar_thing
+foobar_c
+```
+
+## FIXED: Splatting merge anchor lists
+Set `--yaml-fix-merge-anchor-to-spec=true` to get this correct merge behaviour. Note that the keys earlier in the merge anchors sequence override later ones
+
+Given a sample.yml file of:
+```yaml
+foo: &foo
+  a: foo_a
+  thing: foo_thing
+  c: foo_c
+bar: &bar
+  b: bar_b
+  thing: bar_thing
+  c: bar_c
+foobarList:
+  b: foobarList_b
+  !!merge <<:
+    - *foo
+    - *bar
+  c: foobarList_c
+foobar:
+  c: foobar_c
+  !!merge <<: *foo
+  thing: foobar_thing
+```
+then
+```bash
+yq '.foobarList[]' sample.yml
+```
+will output
+```yaml
+foobarList_b
+foo_thing
+foobarList_c
+foo_a
+```
+

pkg/yqlib/operator_traverse_path_test.go

@@ -679,6 +679,6 @@ func TestTraversePathOperatorAlignedToSpecScenarios(t *testing.T) {
 	for _, tt := range append(fixedTraversePathOperatorScenarios, traversePathOperatorScenarios...) {
 		testScenario(t, &tt)
 	}
-	appendOperatorDocumentScenario(t, "anchor-and-alias-operators", fixedAnchorOperatorScenarios)
+	appendOperatorDocumentScenario(t, "traverse-read", fixedTraversePathOperatorScenarios)
 	ConfiguredYamlPreferences.FixMergeAnchorToSpec = false
 }