From da1a11bde6dffa689fe674e4ba9f126f9fabb76c Mon Sep 17 00:00:00 2001
From: Ignace Nyamagana Butera <nyamsprod@gmail.com>
Date: Mon, 15 Jul 2019 12:32:43 +0200
Subject: [PATCH] Improve XMLConverter::import documentation

---
 docs/9.0/converter/xml.md | 54 +++++++++++++++++++++++++--------------
 1 file changed, 35 insertions(+), 19 deletions(-)

diff --git a/docs/9.0/converter/xml.md b/docs/9.0/converter/xml.md
index 54b171f4..33ee770a 100644
--- a/docs/9.0/converter/xml.md
+++ b/docs/9.0/converter/xml.md
@@ -104,15 +104,24 @@ echo htmlentities($dom->saveXML());
 
 <p class="message-info">If needed you can use the <a href="/9.0/converter/charset/">CharsetConverter</a> object to correctly encode your CSV records before conversion.</p>
 
-## Importing into a DOMDocument
+## Import
 
-Starting with version 9.3.0 you can now import the tabular data into an already existing `DOMDocument` object. Do to so you need to use the newly added method `XMLConverter::import`.
-This methods takes two arguments:
+<p class="message-info">New feature introduced in <code>version 9.3.0</code></p>
+
+~~~php
+public XMLConverter::import(iterable $records, DOMDocument $doc): DOMElement
+~~~
+
+Instead of converting your tabular data into a full XML document you can now import it into an already existing `DOMDocument` object.
+Do to so you need to specify which document the data should be imported into using the  `XMLConverter::import` method.
+
+This method takes two arguments:
 
 - the tabular data as defined for the `XMLConverter::convert` method;
 - a `DOMDocument` object to import the data into.
 
- Of note the resulting DOMElement is attached to the given DOMDocument object but still need to be made visible by using a DOM insertion method like `appendChild` or `insertBefore`.
+ Of note the resulting `DOMElement` is attached to the given `DOMDocument` object but not yet included in the document tree.
+ To include it, you still need to call a DOM insertion method like `appendChild` or `insertBefore` with a node that *is* currently in the document tree.
  
  ~~~php
  use League\Csv\XMLConverter;
@@ -123,7 +132,7 @@ This methods takes two arguments:
  $csv->setDelimiter(';');
  $csv->setHeaderOffset(0);
  
- $stmt = (new Statement())
+ $stmt = (new Statement())`
      ->where(function (array $record) {
          return 'Anaïs' === $record['prenoms'];
      })
@@ -140,6 +149,8 @@ This methods takes two arguments:
  $records = $stmt->process($csv);
  
  $dom = new DOMDocument('1.0');
+ $dom->loadXML('<root><header><name>My CSV Document</name></header></root>');
+  
  $data = $converter->import($records, $dom);
  $dom->appendChild($data);
  $dom->formatOutput = true;
@@ -148,18 +159,23 @@ This methods takes two arguments:
  echo '<pre>', PHP_EOL;
  echo htmlentities($dom->saveXML());
  // <?xml version="1.0" encoding="iso-8859-15"?>
- // <csv>
- //   <record offset="71">
- //     <field name="prenoms">Anaïs</field>
- //     <field name="nombre">137</field>
- //     <field name="sexe">F</field>
- //     <field name="annee">2004</field>
- //   </record>
- //   <record offset="1099">
- //     <field name="prenoms">Anaïs</field>
- //     <field name="nombre">124</field>
- //     <field name="sexe">F</field>
- //     <field name="annee">2005</field>
- //   </record>
- // </csv>
+ // <root>
+ //   <header>
+ //     <name>My CSV Document</name>
+ //   </header>
+ //   <csv>
+ //     <record offset="71">
+ //       <field name="prenoms">Anaïs</field>
+ //       <field name="nombre">137</field>
+ //       <field name="sexe">F</field>
+ //       <field name="annee">2004</field>
+ //     </record>
+ //     <record offset="1099">
+ //       <field name="prenoms">Anaïs</field>
+ //       <field name="nombre">124</field>
+ //       <field name="sexe">F</field>
+ //       <field name="annee">2005</field>
+ //     </record>
+ //   </csv>
+ // </root>
  ~~~