diff --git a/pkg/yqlib/doc/usage/xml.md b/pkg/yqlib/doc/usage/xml.md
index eee366c4..79f7c902 100644
--- a/pkg/yqlib/doc/usage/xml.md
+++ b/pkg/yqlib/doc/usage/xml.md
@@ -22,3 +22,221 @@ XML nodes that have attributes then plain content, e.g:
The content of the node will be set as a field in the map with the key "+content". Use the `--xml-content-name` flag to change this.
+## Parse xml: simple
+Given a sample.xml file of:
+```xml
+
+meow
+```
+then
+```bash
+yq e -p=xml '.' sample.xml
+```
+will output
+```yaml
+cat: meow
+```
+
+## Parse xml: array
+Consecutive nodes with identical xml names are assumed to be arrays.
+
+Given a sample.xml file of:
+```xml
+
+1
+2
+```
+then
+```bash
+yq e -p=xml '.' sample.xml
+```
+will output
+```yaml
+animal:
+ - "1"
+ - "2"
+```
+
+## Parse xml: attributes
+Attributes are converted to fields, with the attribute prefix.
+
+Given a sample.xml file of:
+```xml
+
+
+ 7
+
+```
+then
+```bash
+yq e -p=xml '.' sample.xml
+```
+will output
+```yaml
+cat:
+ +legs: "4"
+ legs: "7"
+```
+
+## Parse xml: attributes with content
+Content is added as a field, using the content name
+
+Given a sample.xml file of:
+```xml
+
+meow
+```
+then
+```bash
+yq e -p=xml '.' sample.xml
+```
+will output
+```yaml
+cat:
+ +content: meow
+ +legs: "4"
+```
+
+## Parse xml: with comments
+A best attempt is made to preserve comments.
+
+Given a sample.xml file of:
+```xml
+
+
+
+
+ 3
+
+
+ 4
+
+
+
+
+
+
+```
+then
+```bash
+yq e -p=xml '.' sample.xml
+```
+will output
+```yaml
+# before cat
+cat:
+ # in cat before
+ x: "3" # multi
+ # line comment
+ # for x
+ y:
+ # in y before
+ d: "4" # in d before in d after
+ # in y after
+
+# after cat
+```
+
+## Encode xml: simple
+Given a sample.yml file of:
+```yaml
+cat: purrs
+```
+then
+```bash
+yq e -o=xml '.' sample.yml
+```
+will output
+```xml
+purrs
+```
+
+## Encode xml: array
+Given a sample.yml file of:
+```yaml
+pets:
+ cat:
+ - purrs
+ - meows
+```
+then
+```bash
+yq e -o=xml '.' sample.yml
+```
+will output
+```xml
+
+ purrs
+ meows
+
+```
+
+## Encode xml: attributes
+Fields with the matching xml-attribute-prefix are assumed to be attributes.
+
+Given a sample.yml file of:
+```yaml
+cat:
+ +name: tiger
+ meows: true
+
+```
+then
+```bash
+yq e -o=xml '.' sample.yml
+```
+will output
+```xml
+
+ true
+
+```
+
+## Encode xml: attributes with content
+Fields with the matching xml-content-name is assumed to be content.
+
+Given a sample.yml file of:
+```yaml
+cat:
+ +name: tiger
+ +content: cool
+
+```
+then
+```bash
+yq e -o=xml '.' sample.yml
+```
+will output
+```xml
+cool
+```
+
+## Encode xml: comments
+A best attempt is made to copy comments to xml.
+
+Given a sample.yml file of:
+```yaml
+# above_cat
+cat: # inline_cat
+ # above_array
+ array: # inline_array
+ - val1 # inline_val1
+ # above_val2
+ - val2 # inline_val2
+# below_cat
+
+```
+then
+```bash
+yq e -o=xml '.' sample.yml
+```
+will output
+```xml
+
+ val1
+ val2
+
+```
+
diff --git a/pkg/yqlib/xml_test.go b/pkg/yqlib/xml_test.go
index e888a506..6550da80 100644
--- a/pkg/yqlib/xml_test.go
+++ b/pkg/yqlib/xml_test.go
@@ -58,16 +58,33 @@ type xmlScenario struct {
scenarioType string
}
+var inputXmlWithComments = `
+
+
+
+ 3
+
+
+ 4
+
+
+
+
+
+`
+
var expectedDecodeYamlWithComments = `D0, P[], (doc)::# before cat
cat:
- # in cat
- x: "3" # xca
- # cool
- # smart
+ # in cat before
+ x: "3" # multi
+ # line comment
+ # for x
y:
- # befored
- d: "4" # ind ind2
- # afterd
+ # in y before
+ d: "4" # in d before in d after
+ # in y after
# after cat
`
@@ -89,74 +106,75 @@ var expectedXmlWithComments = `34",
- expected: expectedDecodeYamlWithComments,
- scenarioType: "decode",
+ input: "cat:\n ++name: tiger\n meows: true\n",
+ expected: "\n true\n\n",
+ scenarioType: "encode",
+ },
+ {
+ description: "Encode xml: attributes with content",
+ subdescription: "Fields with the matching xml-content-name is assumed to be content.",
+ input: "cat:\n +name: tiger\n +content: cool\n",
+ expected: "cool\n",
+ scenarioType: "encode",
+ },
+ {
+ description: "Encode xml: comments",
+ subdescription: "A best attempt is made to copy comments to xml.",
+ input: yamlWithComments,
+ expected: expectedXmlWithComments,
+ scenarioType: "encode",
},
- // {
- // description: "Encode xml: simple",
- // input: "cat: purrs",
- // expected: "purrs\n",
- // scenarioType: "encode",
- // },
- // {
- // description: "Encode xml: array",
- // input: "pets:\n cat:\n - purrs\n - meows",
- // expected: "\n purrs\n meows\n\n",
- // scenarioType: "encode",
- // },
- // {
- // description: "Encode xml: attributes",
- // subdescription: "Fields with the matching xml-attribute-prefix are assumed to be attributes.",
- // input: "cat:\n +name: tiger\n meows: true\n",
- // expected: "\n true\n\n",
- // scenarioType: "encode",
- // },
- // {
- // skipDoc: true,
- // input: "cat:\n ++name: tiger\n meows: true\n",
- // expected: "\n true\n\n",
- // scenarioType: "encode",
- // },
- // {
- // description: "Encode xml: attributes with content",
- // subdescription: "Fields with the matching xml-content-name is assumed to be content.",
- // input: "cat:\n +name: tiger\n +content: cool\n",
- // expected: "cool\n",
- // scenarioType: "encode",
- // },
- // {
- // description: "Encode xml: comments",
- // subdescription: "A best attempt is made to copy comments to xml.",
- // input: yamlWithComments,
- // expected: expectedXmlWithComments,
- // scenarioType: "encode",
- // },
// {
// skipDoc: true,
// input: "value",