Improve v9 documentation on converters

docs/9.0/converter/html.md

@@ -1,36 +1,50 @@
 ---
 layout: default
-title: Records conversion in popular formats
+title: Converting a CSV into an HTML table
 ---
 
 # HTML conversion
 
-This converter convert a CSV records collection into an HTML table.
+`HTMLConverter` converts a CSV records collection into a HTML Table by implementing the [Converter interface](/9.0/converter/#converter-interface) and using the [inputEncoding method](/9.0/converter/#records-input-encoding).
+
 
 ## Settings
 
+### HTMLConverter::className
+
 ~~~php
 <?php
 public HTMLConverter::className(string $class_name): self
+~~~
+
+This method sets the optional table `class` attribute name. If none is uses it will default to `table-csv-data`.
+
+### HTMLConverter::recordOffsetAttributeName
+
+~~~php
+<?php
 public HTMLConverter::recordOffsetAttribute(string $attribute_name): self
-public HTMlConverter::fieldAttributeName(string $attribute_name): self
 ~~~
 
+This method sets the optional attribute name for the record offset on the HTML `tr` tag. If none is use or an empty string is given, the record offset information won't be exported to the HTML table
 
-- `HTMLConverter::className` sets the optional table `class` attribute name. If none is uses it will default to `table-csv-data`;
+### HTMLConverter::fieldAttributeName
 
-- `HTMLConverter::recordOffsetAttributeName` sets the optional attribute name for the record offset on the HTML `tr` tag. If none is use or an empty string is given, the record offset information won't be exported to the HTML table;
+~~~php
+<?php
+public HTMLConverter::fieldAttributeName(string $attribute_name): self
+~~~
 
-- `HTMLConverter::fieldAttributeName` sets the optional attribute name for the field name on the HTML `td` tag. If none is use or an empty string is given, the field name information won't be exported to the HTML table;
+This method sets the optional attribute name for the field name on the HTML `td` tag. If none is use or an empty string is given, the field name information won't be exported to the HTML table;
 
-## Convertion
+## Conversion
 
 ~~~php
 <?php
-public HTMlConverter::convert(iterable $records): string
+public HTMLConverter::convert(iterable $records): string
 ~~~
 
-All convertion methods only accepts an `iterable` which represents the records collection.
+The `HTMLConverter::convert` accepts an `iterable` which represents the records collection and returns a string.
 
 ~~~php
 <?php

docs/9.0/converter/index.md

@@ -5,45 +5,47 @@ title: Records conversion in popular formats
 
 # Records conversion
 
+## Converter Interface
+
 The package provides classes which convert any collection of CSV records into:
 
-- a `DOMDocument` object using the [XMLConveter](/9.0/converter/xml/) class;
-- a HTML table using the [HTMLConveter](/9.0/converter/html/) class;
-- a Json string using the [JsonConverter](/9.0/converter/json/);
+- a `DOMDocument` object using the [XMLConverter](/9.0/converter/xml/) class;
+- a HTML table using the [HTMLConverter](/9.0/converter/html/) class;
+- a Json string using the [JsonConverter](/9.0/converter/json/) class;
 
-All theses classes implements the `Converter` interface to convert the CSV records collection.
+All theses classes implements the `Converter` interface.
 
 ~~~php
 <?php
 
 public Converter::convert(iterable $records): mixed
 ~~~
 
-This CSV records collection can be:
+This `$records` argument can be:
 
 - a [Reader](/9.0/reader/) object
 - a [RecordSet](/9.0/reader/records/) object;
 - or any `array` or `Traversable` object which represents a collection of CSV records;
 
-<p class="message-warning">A <code>League\Csv\Writer</code> object can not be converted.</p>
+<p class="message-warning"><strong>Warning:</strong> A <code>League\Csv\Writer</code> object can not be converted.</p>
 
-## Converter are immutable
+## Converters are immutable
 
-Before convertion your records, you will want to configure your converter. Each provided converter exposes additional methods to correctly set them.
+Before convertion your records, you will want to configure your converter. Each provided converter exposes additional methods to correctly transcode the collection.
 
-When building a `Converter` object, the methods do not need to be called in any particular order, and may be called multiple times. Because the `Converter` object is immutable, each time its setter methods are called they will return a new object without modifying the current object.
+When building a converter object, the methods do not need to be called in any particular order, and may be called multiple times. Because all provided converter object are immutable, each time their setter methods are called they will return a new object without modifying the current object.
 
 ## Records Input Encoding
 
 ~~~php
 <?php
 
-public Converter::inputEncoding(string $charset): self
+public function ConverterObject::inputEncoding(string $charset): self
 ~~~
 
-<p class="message-warning">Out of the box, all converters assume that your are submitting <code>UTF-8</code> encoded records. If your data is not <code>UTF-8</code> encoded some unexpected results or exception may be thrown when trying to convert your data.</p>
+Out of the box, all converters assume that your are submitting `UTF-8` encoded records. If your data is not `UTF-8` encoded some unexpected results or exception may be thrown when trying to convert your data.
 
-If the submitted records comes from a `Reader` object which supports PHP stream filters then it's recommended to use the library [stream filtering mechanism](/9.0/connections/filters/) to convert your data prior to converting it. Otherwise you can fallback to using the `Converter::inputEncoding` method exposed on each provided converter.
+If your data is not `UTF-8` encoded use the `inputEncoding` method exposed on each provided converter
 
 ~~~php
 <?php
@@ -58,4 +60,6 @@ $converter = (new JsonConverter())->inputEncoding('iso-8859-15');
 $json = $converter->convert($csv);
 ~~~
 
-<p class="message-warning"><code>Converter::inputEncoding</code> is not part of the <code>Converter</code> interface.</p>
+<p class="message-info"><strong>Tips:</strong> If your records collection comes from a <code>Reader</code> object which supports PHP stream filters then it's recommended to use the library <a href="/9.0/connections/filters/">stream filtering mechanism</a> to first encode your data in <code>UTF-8</code>.</p>
+
+<p class="message-warning"><strong>Warning:</strong> <code>inputEncoding</code> is not part of the <code>Converter</code> interface.</p>

docs/9.0/converter/json.md

@@ -1,47 +1,77 @@
 ---
 layout: default
-title: Records conversion in popular formats
+title: Converting a CSV into a JSON string
 ---
 
 # JSON conversion
 
-This converter convert a CSV records collection into a JSON string using PHP's `json_encode` function.
+`JsonConverter` converts a CSV records collection into a JSON string by implementing the [Converter interface](/9.0/converter/#converter-interface) and using the [inputEncoding method](/9.0/converter/#records-input-encoding).
 
 ## Settings
 
+### JsonConverter::preserveRecordOffset
+
 ~~~php
 <?php
+
 public JsonConverter::preserveRecordOffset(bool $preserve_offset): self
-public JsonConverter::options(int options = 0, int $depth = 512): self
 ~~~
 
+This method tells whether the converter should keep or not the CSV record offset in the JSON output. By default, record offsets are not preserved.
 
-- `JsonConverter::preserveRecordOffset` tells whether the converter should keep or not the CSV record offset in the JSON output. By default, the record offset are not preserved.
+### JsonConverter::options
 
-- `JsonConverter::options` sets PHP's `json_encode` optional arguments.
+~~~php
+<?php
 
+public JsonConverter::options(int options = 0, int $depth = 512): self
+~~~
+
+This method sets PHP's `json_encode` optional arguments.
 
-## Convertion
+## Conversion
 
 ~~~php
 <?php
 public JsonConverter::convert(iterable $records): string
 ~~~
 
+The `JsonConverter::convert` accepts an `iterable` which represents the records collection and returns a string.
+
 If a error occurs during the convertion an `RuntimeException` exception is thrown with additional information regarding the error.
 
 ~~~php
 <?php
 
 use League\Csv\JsonConverter;
+use League\Csv\Reader;
 
-$csv = new SplFileObject('/path/to/french.csv', 'r');
-$csv->setFlags(SplFileObject::READ_CSV | SplFileObject::SKIP_EMPTY);
+$csv = Reader::createFromPath('/path/to/file.csv', 'r')
+   ->setHeaderOffset(0)
+;
 
 $json = (new JsonConverter())
     ->options(JSON_PRETTY_PRINT)
     ->convert($csv)
 ;
-//may trigger an error if for instance the
-//CSV collection is not in a UTF-8 encoding
+
+echo '<pre>', $json, PHP_EOL;
+// [
+//     {
+//         "firstname": "john",
+//         "lastname": "doe",
+//         "email": "john.doe@example.com"
+//     },
+//     {
+//         "firstname": "jane",
+//         "lastname": "doe",
+//         "email": "jane.doe@example.com"
+//     },
+//     ...
+//     {
+//         "firstname": "san",
+//         "lastname": "goku",
+//         "email": "san.goku@dragon-ball.super"
+//     }
+// ]
 ~~~

docs/9.0/converter/xml.md

@@ -1,36 +1,56 @@
 ---
 layout: default
-title: Records conversion in popular formats
+title: Converting a CSV into a XML DOMDocument object
 ---
 
 # XML conversion
 
-This converter converts a CSV records collection into a PHP `DOMDocument`.
+`XMLConverter` converts a CSV records collection into a PHP `DOMDocument` by implementing the [Converter interface](/9.0/converter/#converter-interface) and using the [inputEncoding method](/9.0/converter/#records-input-encoding).
 
 ## Settings
 
+### XMLConverter::rootElement
+
 ~~~php
 <?php
 
 public XMLConverter::rootElement(string $node_name): self
-public XMLConverter::recordElement(string $node_name, string $offset_attribute_name = ''): self
-public XMLConverter::fieldElement(string $node_name, string $field_attribute_name = ''): self
 ~~~
 
-`XMLConverter::rootElement` sets the XML root name which defaults to `csv`.
+This method sets the XML root name which defaults to `csv`.
+
+### XMLConverter::recordElement
+
+~~~php
+<?php
+
+public XMLConverter::recordElement(string $node_name, string $record_offset_attribute_name = ''): self
+~~~
+
+This method sets the XML record name which defaults to `row`.
+
+Optionnally you can preserve the record offset by providing a name for its attribute on the XML record element using the `$record_offset_attribute_name` argument. If this argument is empty, the offset attribute information won't be added. By default, the attribute is not provided.
+
+### XMLConverter::fieldElement
+
+~~~php
+<?php
+
+public XMLConverter::fieldElement(string $node_name, string $fieldname_attribute_name = ''): self
+~~~
 
-`XMLConverter::recordElement` sets the XML record name which defaults to `row`. Optionnally you can preserve the record offset by providing a name for the its attribute on the XML record element using the `$offset_attribute_name` argument. If this argument is empty or not provided, the offset attribute information won't be added. By default, the attribute is not provided.
+This method sets the XML field name which defaults to `cell`.
 
-`XMLConverter::fieldElement` sets the XML field name which defaults to `cell`. Optionnally you can preserve the field name by providing a name for the its attribute on the XML field element using the `$field_attribute_name` argument. If this argument is empty or not provided, the field name information won't be added. By default, the attribute is not provided.
+Optionnally you can preserve the field name by providing a name for its attribute on the XML field element using the `$fieldname_attribute_name` argument. If this argument is empty, the fieldname information won't be added. By default, the attribute is not provided.
 
-## Convertion
+## Conversion
 
 ~~~php
 <?php
 public XMLConverter::convert(iterable $records): DOMDocument
 ~~~
 
-All convertion methods only accepts an `iterable` which represents the records collection.
+The `XMLConverter::convert` accepts an `iterable` which represents the records collection and returns a `DOMDocument` object.
 
 ~~~php
 <?php

src/JsonConverter.php

@@ -100,7 +100,7 @@ public function convert($records)
             $records = array_values($records);
         }
 
-        $json = json_encode($records, $this->options, $this->depth);
+        $json = @json_encode($records, $this->options, $this->depth);
         if (JSON_ERROR_NONE === json_last_error()) {
             return $json;
         }