Improve documentation

Author: nyamsprod

docs/9.0/connections/bom.md

@@ -5,12 +5,10 @@ title: BOM sequence detection and addition
 
 # BOM sequences
 
-## Detecting the BOM sequence
+## Definition
 
 To improve interoperability with programs interacting with CSV, the package now provides an enum `Bom` to help you detect the appropriate <abbr title="Byte Order Mark">BOM</abbr> sequence.
 
-### BOM definition
-
 The `Bom` enum provides the following value :
 
 - `Bom::Utf8` : which handles the `UTF-8` `BOM` sequence;
@@ -19,7 +17,9 @@ The `Bom` enum provides the following value :
 - `Bom::utf32Be` : which handles the `UTF-32` `BOM` with Big-Endian sequence;
 - `Bom::utf32Le` : which handles the `UTF-32` `BOM` with Little-Endian sequence;
 
-### Detecting the BOM from a sequence of characters
+## Detection
+
+### From a Sequence of Characters
 
 ```php
 Bom::fromSequence(mixed $sequence): Bom
@@ -37,7 +37,7 @@ Bom::tryFromSequence(Bom::Utf8->value.'hello world!'); //returns Bom::Utf8
 Bom::tryFromSequence('hello world!'.Bom::Utf16Le->value); //returns null
 ```
 
-### Detecting the BOM from the encoding name
+### From the Encoding Name
 
 ```php
 Bom::fromEncoding(string $encoding): Bom
@@ -55,7 +55,7 @@ Bom::tryFromEncoding('u_t_F--8'); //returns Bom::Utf8
 Bom::tryFromEncoding('foobar'); //returns null
 ```
 
-### Accessing the BOM properties
+## Accessing the BOM properties
 
 Once you have a valid `Bom` instance you can access:
 
@@ -99,7 +99,7 @@ bom_match(ByteSequence::BOM_UTF8.'hello world!'); //returns '\xEF\xBB\xBF'
 bom_match('hello world!'.ByteSequence::BOM_UTF16_BE); //returns ''
 ```
 
-## Managing CSV documents BOM sequence
+## Handling CSV documents
 
 ### Detecting the BOM sequence
 

docs/9.0/connections/controls.md

@@ -5,18 +5,13 @@ title: Csv character controls
 
 # CSV character controls
 
-To correctly parse a CSV document you are required to set the character controls to be used by the `Reader` or the `Writer` object.
+To correctly parse a CSV document, you are required to set the character controls to be used
+by the `Reader` or the `Writer` object.
 
 ## The delimiter character
 
-### Description
-
-```php
-public AbstractCsv::setDelimiter(string $delimiter): self
-public AbstractCsv::getDelimiter(void): string
-```
-
-### Example
+The `getDelimiter()` and `setDelimiter()` methods set and returns the CSV delimiter character
+used by the underlying class. The setter method expects a single byte character string to be used.
 
 ```php
 use League\Csv\Reader;
@@ -32,14 +27,8 @@ $delimiter = $csv->getDelimiter(); //returns ";"
 
 ## The enclosure character
 
-### Description
-
-```php
-public AbstractCsv::setEnclosure(string $enclosure): self
-public AbstractCsv::getEnclosure(void): string
-```
-
-### Example
+The `getEnclosure()` and `setEnclosure()` methods set and returns the CSV enclosure character
+used by the underlying class. The setter method expects a single byte character string to be used.
 
 ```php
 use League\Csv\Writer;
@@ -55,22 +44,18 @@ $enclosure = $csv->getEnclosure(); //returns "|"
 
 ## The escape character
 
-This is a PHP specific control character which sometimes interferes with CSV parsing and writing.
-It is recommended in versions preceding `9.2.0` to never change its default value unless you do understand its usage and its consequences.
+The `getEscape()` and `setEscape()` methods set and returns the CSV escape character
+used by the underlying class. The setter method expects a single byte character string to be used.
+
+This is a PHP specific control character that sometimes interferes with CSV parsing and writing.
+It is recommended in versions preceding `9.2.0` to never change its default value unless you do
+understand its usage and its consequences.
 
 <p class="message-warning">Starting with version <code>PHP7.4</code> it is recommended to use the library
 with the escape parameter equal to the empty string.
 see <a href="https://wiki.php.net/rfc/deprecations_php_8_4#deprecate_proprietary_csv_escaping_mechanism">Deprecation for PHP8.4</a> and
 <a href="https://nyamsprod.com/blog/csv-and-php8-4/">CSV and PHP8.4</a> for more information.</p>
 
-### Description
-
-```php
-public AbstractCsv::setEscape(string $escape): self
-public AbstractCsv::getEscape(void): string
-```
-
-### Example
 
 ```php
 use League\Csv\Reader;

docs/9.0/connections/instantiation.md

@@ -27,7 +27,7 @@ $writer = Writer::fromString('john,doe,[email protected]');
 
 <p class="message-notice">The <code>$content</code> argument default value is an empty string to ease usage.</p>
 
-## Loading from a file or a stream
+## Loading from a file pointer
 
 <p class="message-notice">This new API is introduced in version <code>9.27.0</code></p>
 
@@ -162,7 +162,7 @@ $reader = Reader::createFromFileObject(new SplFileObject('/path/to/your/csv/file
 $writer = Writer::createFromFileObject(new SplTempFileObject());
 ```
 
-## Accessing the CSV document path
+## Accessing the document path
 
 <p class="message-notice">New in version <code>9.2.0</code></p>
 

docs/9.0/converter/charset.md

@@ -40,7 +40,7 @@ $records = $encoder->convert($csv);
 
 The resulting data is converted from `iso-8859-15` to the default `UTF-8` since no output encoding charset was set using the `CharsertConverter::outputEncoding` method.
 
-## CharsetConverter as a Writer formatter
+## As a Writer formatter
 
 ```php
 public CharsetConverter::__invoke(array $record): array
@@ -64,22 +64,22 @@ $writer->insertOne(["foo", "bébé", "jouet"]);
 //all 'utf-8' characters are now automatically encoded into 'iso-8859-15' charset
 ```
 
-## CharsetConverter as a PHP stream filter
+## As a PHP stream filter
 
 ```php
 public static CharsetConverter::addTo(AbstractCsv $csv, string $input_encoding, string $output_encoding): AbstractCsv
 public static CharsetConverter::register(): void
 public static CharsetConverter::getFiltername(string $input_encoding, string $output_encoding): string
 ```
 
-### Usage with CSV objects
+### With CSV object
 
-If your CSV object supports PHP stream filters then you can use the `CharsetConverter` class as a PHP stream filter using the library [stream filtering mechanism](/9.0/connections/filters/) instead.
+If your CSV object supports PHP stream filters; then you can use the `CharsetConverter` class as a PHP stream filter using the library [stream filtering mechanism](/9.0/connections/filters/) instead.
 
 The `CharsetConverter::addTo` static method:
 
 - registers the `CharsetConverter` class under the generic filtername `convert.league.csv.*` if it is not registered yet;
-- configures the stream filter using the supplied parameters;
+- configure the stream filter using the supplied parameters;
 - adds the configured stream filter to the submitted CSV object;
 
 ```php
@@ -93,7 +93,7 @@ $writer->insertOne(["foo", "bébé", "jouet"]);
 //all 'utf-8' characters are now automatically encoded into 'iso-8859-15' charset
 ```
 
-### Usage with PHP stream resources
+### With PHP Stream
 
 To use this stream filter outside `League\Csv` objects you need to:
 

docs/9.0/converter/json.md

@@ -38,7 +38,7 @@ new JsonConverter()->download($record); //new and fast-forward method usage
 
 Prior to converting your collection into a JSON structure, you may wish to configure it.
 
-### JSON encode flags
+### Encoding Flags
 
 ```php
 public JsonConverter::addFlags(int ...$flag): self
@@ -97,7 +97,7 @@ $converter = (new JsonConverter())->withPrettyPrint(2);
 
 will produce a JSON with an indentation size of `2`.
 
-### Json encode depth
+### Encoding Depth
 
 ```php
 public JsonConverter::depth(int $depth): self
@@ -111,7 +111,7 @@ $converter = (new JsonConverter())->depth(2);
 $converter->depth; //returns the actual depth value (as used by json_encode) 
 ```
 
-### Json encode indentation
+### Encode Indentation
 
 <p class="message-warning">This method is deprecated as of version <code>9.19.0</code> use
 <code>JsonConverter::withPrettyPrint</code> instead and add the <code>$identSize</code> argument
@@ -131,7 +131,7 @@ size is the same as in PHP (ie : 4 characters long).
 $converter->indentSize; //returns the value used
 ```
 
-### Json encode formatter
+### Encoding Formatter
 
 ```php
 public JsonConverter::formatter(?callable $formatter): self
@@ -162,7 +162,7 @@ $converter = (new JsonConverter())->chunkSize(1_000);
 $converter->chunkSize; //returns the value used
 ```
 
-### JsonConverter::when
+### Conditional Settings
 
 <p class="message-info">New feature introduced in version <code>9.22.0</code></p>
 

docs/9.0/index.md

@@ -13,9 +13,7 @@ layout: default
 
 **League\Csv** is a simple library to ease CSV document [loading](/9.0/connections/) as well as [writing](/9.0/writer/), [selecting](/9.0/reader/) and [converting](/9.0/converter/) CSV records.
 
-## Usage
-
-### Parsing a CSV document
+## Parsing a CSV document
 
 Access and filter records from a CSV document saved on the local filesystem.
 
@@ -39,7 +37,7 @@ foreach ($records as $record) {
 }
 ```
 
-### Exporting a database table as a CSV document
+## Exporting a database table as a CSV document
 
 Fetch data using a `PDOStatement` object, then create a CSV document which is output to the browser.
 
@@ -76,7 +74,7 @@ $csv->output('users.csv');
 die;
 ```
 
-### Importing CSV records into a database table
+## Importing CSV records into a database table
 
 Import records from a CSV document into a database using a `PDOStatement` object
 
@@ -104,7 +102,7 @@ foreach ($csv as $record) {
 }
 ```
 
-### Encoding a CSV document into a given charset
+## Encoding a CSV document into a given charset
 
 It is not possible to detect the character encoding a CSV document (e.g. `UTF-8`, `UTF-16`, etc). However, it *is* possible to detect the input BOM and convert to UTF-8 where necessary.
 
@@ -127,7 +125,7 @@ foreach ($csv as $record) {
 }
 ```
 
-### Converting a CSV document into a XML document
+## Converting a CSV document into a XML document
 
 The `XMLConverter` object provided by this package can easily convert a CSV document into a `DOMDocument` object.
 

docs/9.0/interoperability/enclose-field.md

@@ -16,7 +16,7 @@ The `EncloseField` is a PHP stream filter which forces the `Writer` class to enc
 <code>Writer::forceEnclosure</code> method for better results and improved DX. Please refer to
 <a href="/9.0/writer/#force-enclosure">its documentation</a> for more informations.</p>
 
-## Usage with Writer objects
+## With Writer objects
 
 ```php
 public static EncloseField::addTo(Writer $csv, string $sequence): Writer
@@ -40,7 +40,7 @@ $writer->output('mycsvfile.csv'); //outputting a CSV Document with all its field
 
 <p class="message-warning">The <code>$sequence</code> argument should be a sequence containing at least one character that forces <code>fputcsv</code> to enclose the field value. If not, an <code>InvalidArgumentException</code> exception will be thrown.</p>
 
-## Usage with PHP stream resources
+## With PHP Streams
 
 ```php
 public static EncloseField::register(): void

docs/9.0/interoperability/escape-formula-injection.md

@@ -57,7 +57,7 @@ $reader->first();
 // the escaping characters are removed.
 ```
 
-## Usage with PHP stream resources
+## Usage with PHP streams
 
 You can use the `EscapeFormula` to format your records before calling `fputcsv` or `SplFileObject::fputcsv`.
 

docs/9.0/interoperability/rfc4180-field.md

@@ -18,7 +18,7 @@ When using this stream filter you can easily create or read a [RFC4180 compliant
 
 <p class="message-warning">Changing the CSV objects control characters <strong>after registering the stream filter</strong> may result in unexpected returned records.</p>
 
-## Usage with League\CSV objects
+## With CSV objects
 
 ```php
 public static RFC4180Field::addTo(AbstractCsv $csv, string $whitespace_replace = ''): AbstractCsv
@@ -74,11 +74,11 @@ $writer->insertOne(['foo bar', 'bar']);
 echo $writer->getContent(); //display ' o bar,baz' instead of 'foo bar,baz'
 ```
 
-### On records insertion
+### On Records Insertion
 
 <p class="message-info">To fully comply with <code>RFC4180</code> you will also need to use <code>League\Csv\Writer::setNewline</code>.</p>
 
-### On records extraction
+### On Records Extraction
 
 Conversely, to read a RFC4180 compliant CSV document, when using the `League\Csv\Reader` object, you just need to add the `League\Csv\RFC4180Field` stream filter as shown below:
 
@@ -95,7 +95,7 @@ foreach ($csv as $record) {
 }
 ```
 
-## Usage with PHP stream resources
+## With PHP streams
 
 ```php
 public static RFC4180Field::register(): void

docs/9.0/reader/tabular-data-reader.md

@@ -5,6 +5,8 @@ title: Tabular Data Reader
 
 # Tabular Data Reader Common API
 
+## Why does it exist?
+
 Introduced in version `9.6` the `League\Csv\TabularDataReader` interface provides a common
 API to works with tabular data like structure. Once implemented, it can be used to work
 with HTML tables, simple RDBMS tables, CSV document and so forth. A tabular data
@@ -44,10 +46,10 @@ leaving your source data unchanged.
 ## Available methods
 
 While the `TabularDataReader` is not a fully fledged collection instance it still exposes a lots of methods
-that fall into the category of records collection manipulations. Because chaining is at the core of most of
-the methods you can be sure that each manipulation returns a new instance preserving your original data.
+that fall into the category of records collection manipulations. Because chaining is at the core of the API,
+most methods return a new instance preserving your original data.
 
-### Countable, IteratorAggregate
+### Counting and traversing the records
 
 Any `TabularDataReader` instance implements the `Countable` and the `IteratorAggregate` interface.
 It means that at any given time you can access the number of elements that are included in the instance