Improve documentation

Author: nyamsprod

README.md

@@ -60,6 +60,19 @@ echo $list->get(-1)->value; //returns '/member/*/comments'
 Parsing and Serializing Structured Fields
 ------------
 
+```php
+use Bakame\Http\StructuredFields;
+
+$dictionary = StructuredFields\Dictionary::fromHttpValue("a=?0,   b,   c=?1; foo=bar");
+echo $dictionary->toHttpValue(); // 'a=?0, b, c;foo=bar'
+
+$list = StructuredFields\OrderedList::fromHttpValue('("foo"; a=1;b=2);lvl=5, ("bar" "baz");lvl=1');
+echo $list->toHttpValue(); // '("foo";a=1;b=2);lvl=5, ("bar" "baz");lvl=1'
+
+$item = StructuredFields\Item::fromHttpValue('"foo";a=1;b=2');
+echo $item->toHttpValue(); // "foo";a=1;b=2
+```
+
 an HTTP field value can be:
 
 - a Dictionary,
@@ -72,19 +85,6 @@ representation of the field and to serialize the value object back to the textua
 - Parsing is done via a common named constructor `fromHttpValue` which expects the Header or Trailer string value.
 - Serializing is done via a common `toHttpValue` public method. The method returns the normalized string representation suited for HTTP textual representation.
 
-```php
-use Bakame\Http\StructuredFields;
-
-$dictionary = StructuredFields\Dictionary::fromHttpValue("a=?0,   b,   c=?1; foo=bar");
-echo $dictionary->toHttpValue(); // "a=?0, b, c;foo=bar"
-
-$list = StructuredFields\OrderedList::fromHttpValue('("foo"; a=1;b=2);lvl=5, ("bar" "baz");lvl=1');
-echo $list->toHttpValue(); // "("foo";a=1;b=2);lvl=5, ("bar" "baz");lvl=1"
-
-$item = StructuredFields\Item::fromHttpValue('"foo";a=1;b=2"');
-echo $item->toHttpValue(); // "foo";a=1;b=2
-```
-
 Building Structured Fields
 ------------
 
@@ -115,53 +115,67 @@ keys are strings and the value are bare items. Their public API is covered in su
 
 **An item without any parameter associated to it is said to be a bare item.**
 
-#### Token Data type
+#### Token type
+
+```php
+use Bakame\Http\StructuredFields;
+
+$token = StructuredFields\Token::fromString('bar')]));
+
+echo $token->toString();         //displays 'bar'
+echo $dictionary->toHttpValue(); //displays 'bar'
+```
 
 The Token data type is a special string as defined in the RFC. To distinguish it from a normal string, the `Bakame\Http\StructuredFields\Token` class is used.
 
 To instantiate the class you are required to use the `Token::fromString` named constructor.
-The class also exposes the complementat=ry public methods `Token::toString` as well as the `Token::toHttpValue` to enable its textual representation.
+The class also exposes the complementary public methods `Token::toString` as well as the `Token::toHttpValue` to enable its textual representation.
+
+#### Byte Sequence type
 
+```php
+use Bakame\Http\StructuredFields;
 
-#### Byte Sequence Data type
+$sequenceFromDecoded = StructuredFields\ByteSequence::fromDecoded("Hello World");
+$sequenceFromEncoded = StructuredFields\ByteSequence::fromEncoded("SGVsbG8gV29ybGQ=");
+
+echo $sequenceFromEncoded->decoded();     //displays 'Hello World'
+echo $sequenceFromDecoded->encoded();     //displays 'SGVsbG8gV29ybGQ='
+echo $sequenceFromDecoded->toHttpValue(); //displays ':SGVsbG8gV29ybGQ=:'
+echo $sequenceFromEncoded->toHttpValue(); //displays ':SGVsbG8gV29ybGQ=:'
+```
 
 The Byte Sequence data type is a special string as defined in the RFC to represent base64 encoded data. To distinguish it from a normal string, 
 the `Bakame\Http\StructuredFields\ByteSequence` class is used.
 
 To instantiate the class you are required to use the `ByteSequence::fromDecoded` or `ByteSequence::fromEncoded` named constructors.
-The class also exposes the complementat=ry public methods `ByteSequence::decoded`, `ByteSequence::encoded` as well as 
+The class also exposes the complementary public methods `ByteSequence::decoded`, `ByteSequence::encoded` as well as 
 the `ByteSequence::toHttpValue` to enable its textual representation.
 
 #### Usages
 
-Instantiation via type recognition is done using the `Item::from` named constructor.
-
-- The first argument represents one of the six (6) item type value;
-- The second argument, which is optional, MUST be an iterable construct where its index represents the parameter key and its value an item or a item type value;
-
 ```php
 use Bakame\Http\StructuredFields;
 
 $item = StructuredFields\Item::from("hello world", ["a" => true]);
-$item->value; //returns "hello world"
-$item->isString(); //return true
-$item->isToken();  //return false
+$item->value;      //returns "hello world"
+$item->isString(); //returns true
+$item->isToken();  //returns false
 $item->parameters->value("a"); //returns true
 ```
 
-Conversely, the `Item::fromPair` is an alternative to the `Item::from`
-which expects a tuple composed by an array as a list where:
+Instantiation via type recognition is done using the `Item::from` named constructor.
 
-- The first member on index `0` represents one of the six (6) item type value;
-- The second optional member, on index `1`, MUST be an iterable construct containing tuples of key-value pairs;
+- The first argument represents one of the six (6) item type value;
+- The second argument, which is optional, MUST be an iterable construct where its index represents the parameter key and its value an item or a item type value;
 
 ```php
 use Bakame\Http\StructuredFields;
 
 $item = StructuredFields\Item::fromPair([
     "hello world", 
     [
-        ["a", StructuredFields\ByteSequence::fromDecoded("Hello World")]
+        ["a", StructuredFields\ByteSequence::fromDecoded("Hello World")],
     ]
 ]);
 $item->value; //returns "hello world"
@@ -171,6 +185,12 @@ $item->parameters->value("a")->decoded(); //returns 'Hello World'
 echo $item->toHttpValue(); //returns "hello world";a=:SGVsbG8gV29ybGQ=:
 ```
 
+Conversely, the `Item::fromPair` is an alternative to the `Item::from`
+which expects a tuple composed by an array as a list where:
+
+- The first member on index `0` represents one of the six (6) item type value;
+- The second optional member, on index `1`, MUST be an iterable construct containing tuples of key-value pairs;
+
 Once instantiated, accessing `Item` properties is done via two (2) readonly properties:
 
 - `Item::value` which returns the instance underlying value
@@ -192,7 +212,17 @@ $item->isInteger(); //return true
 
 ### Containers
 
-The package exposes different ordered maps and lists with different requirements via the following value objects:
+```php
+use Bakame\Http\StructuredFields;
+
+$parameters = StructuredFields\Parameters::fromAssociative(['a' => 1, 'b' => 2, 'c' => "hello world"]);
+count($parameters); // returns 3
+$parameters->isEmpty(); // returns false
+$parameters->toHttpValue(); // returns ';a=1;b=2;c="hello world"'
+$parameters->clear()->isEmpty(); // returns true
+```
+
+The package exposes ordered maps and lists with different requirements via the following value objects:
 
 - `Dictionary`,
 - `Parameters`,
@@ -212,17 +242,29 @@ At any given time it is possible with each of these objects to:
 - For setter methods, Item types are inferred using `Item::from` if a `Item` object is not submitted.
 - Because all containers can be access by their indexes, some changes may re-index them as to not expose missing indexes.
 
+#### Ordered Maps
+
 ```php
 use Bakame\Http\StructuredFields;
 
-$parameters = StructuredFields\Parameters::fromAssociative(['a' => 1, 'b' => 2, 'c' => "hello world"]);
-count($parameters); // returns 3
-$parameters->isEmpty(); // returns false
-$parameters->toHttpValue(); // returns ';a=1;b=2;c="hello world"'
-$parameters->clear()->isEmpty(); // returns true
-```
+$dictionary = StructuredFields\Dictionary::fromPairs([
+    ['b', true],
+]);
+$dictionary
+    ->append('c', StructuredFields\Item::from(true, ['foo' => StructuredFields\Token::fromString('bar')]))
+    ->prepend('a', false)
+    ->toHttpValue(); //returns "a=?0, b, c;foo=bar"
 
-#### Ordered Maps
+$dictionary->has('a');    //return true
+$dictionary->has('foo');  //return false
+$dictionary->pair(1);     //return ['b', Item::fromBoolean(true)]
+$dictionary->hasPair(-1); //return true
+
+echo $dictionary
+    ->append('z', 42.0)
+    ->delete('b', 'c')
+    ->toHttpValue(); //returns "a=?0, z=42.0"
+```
 
 The `Parameters` and the `Dictionary` classes allow associating a string 
 key to its members 
@@ -232,10 +274,13 @@ key to its members
 
 Both classes exposes the following:
 
+named constructors:
+
+- `fromAssociative` instantiates the container with an iterable construct of associative value;
+- `fromPairs` instantiates the container with a list of key-value pairs;
+
 getter methods:
 
-- `fromAssociative` a named constructor to instantiate the container with an iterable construct of associative value;
-- `fromPairs` a named constructor to instantiate the container with a list of key-value pairs;
 - `toPairs` returns an iterator to iterate over the container pairs;
 - `keys` to list all existing keys of the ordered maps as an array list;
 - `has` tell whether a specific element is associated to a given `key`;
@@ -252,26 +297,6 @@ setter methods:
 - `mergeAssociative` merge multiple instances of iterable structure as associative constructs;
 - `mergePairs` merge multiple instances of iterable structure as pairs constructs;
 
-```php
-use Bakame\Http\StructuredFields;
-
-$dictionary = StructuredFields\Dictionary::fromPairs([['b', true]]);
-$dictionary
-    ->append('c', StructuredFields\Item::from(true, ['foo' => StructuredFields\Token::fromString('bar')]))
-    ->prepend('a', false)
-    ->toHttpValue(); //returns "a=?0, b, c;foo=bar"
-
-$dictionary->has('a');    //return true
-$dictionary->has('foo');  //return false
-$dictionary->pair(1);     //return ['b', Item::fromBoolean(true)]
-$dictionary->hasPair(-1); //return true
-
-echo $dictionary
-    ->append('z', 42.0)
-    ->delete('b', 'c')
-    ->toHttpValue(); //returns "a=?0, z=42.0"
-```
-
 The `Parameters` instance exposes the following additional methods:
 
 - `Parameters::values()` to list all existing Bare Items value as an array list;
@@ -298,6 +323,23 @@ $parameters->value('unknown'); // returns null
 
 #### Lists
 
+```php
+use Bakame\Http\StructuredFields;
+
+$innerList = StructuredFields\InnerList::fromList([42, 42.0, "42"], ["a" => true]);
+$innerList->has(2); //return true
+$innerList->has(42); //return false
+$innerList->push(StructuredFields\Token::fromString('forty-two'));
+$innerList->remove(0, 2);
+echo $innerList->toHttpValue(); //returns '(42.0 forty-two);a'
+
+$orderedList = StructuredFields\OrderedList::from(
+    StructuredFields\Item::from("42", ["foo" => "bar"]), 
+    $innerList
+);
+echo $orderedList->toHttpValue(); //returns '"42";foo="bar", (42.0 forty-two);a'
+```
+
 The `OrderedList` and the `InnerList` classes are list of members that act as containers 
 
 The main distinction between `OrderedList` and `InnerList` are:
@@ -308,10 +350,13 @@ The main distinction between `OrderedList` and `InnerList` are:
 
 Both classes exposes the following:
 
+named constructors:
+
+- `fromList` instantiates the container with a list of members in an iterable construct;
+- `from` instantiates the container with a list of members as variadic;
+
 getter methods:
 
-- `fromList` a named constructor to instantiate the container with a list of members in an iterable construct;
-- `from` a named constructor to instantiate the container with a list of members as variadic;
 - `get` to access an element at a given index (negative indexes are supported)
 - `has` tell whether an element is attached to the container using its `index`;
 
@@ -323,23 +368,6 @@ setter methods
 - `replace` to replace an element at a given position in the list;
 - `remove` to remove elements based on their position;
 
-```php
-use Bakame\Http\StructuredFields;
-
-$innerList = StructuredFields\InnerList::fromList([42, 42.0, "42"], ["a" => true]);
-$innerList->has(2); //return true
-$innerList->has(42); //return false
-$innerList->push(StructuredFields\Token::fromString('forty-two'));
-$innerList->remove(0, 2);
-echo $innerList->toHttpValue(); //returns '(42.0 forty-two);a'
-
-$orderedList = StructuredFields\OrderedList::from(
-    StructuredFields\Item::from("42", ["foo" => "bar"]), 
-    $innerList
-);
-echo $orderedList->toHttpValue(); //returns '"42";foo="bar", (42.0 forty-two);a'
-```
-
 A `Parameters` instance can be associated to an `InnerList` using the same API as for the `Item` value object.
 
 ```php