Improve documentation structure

Author: nyamsprod

docs/00-intro.md

@@ -56,8 +56,7 @@ composer require bakame/http-structured-fields
 
 - [Basic usage](01-basic-usage.md)
 - [Parsing and Serializing](02-parsing-serializing.md)
-- [Structured Field Value Types](03-value-types.md)
-- [The Item Data Type](04-item.md)
-- [The Structured Field Containers](05-containers.md)
-- [HTTP Fields Validation](06-validation.md)
+- [Accessing The Field Values](03-field-values.md)
+- [Working with the Containers Data Type](04-containers.md)
+- [Structured Field Validation](05-validation.md)
 - [Interacting with the PHP Ecosystem](07-extensions.md)

docs/02-parsing-serializing.md

@@ -161,4 +161,4 @@ The `toHttpValue` method applies by default all the normalizations recommended b
 > This is the mechanism used by the `DataType::serialize` method. Once the Structured
 > field has been created, the method calls its `toHttpValue` method.
 
-← [Basic Usage](01-basic-usage.md)  |  [Value Types](03-value-types.md) →
+← [Basic Usage](01-basic-usage.md)  |  [Accessing Field Values](03-field-values.md) →

docs/03-value-types.md renamed to docs/03-field-values.md

@@ -1,9 +1,9 @@
 ---
-title: HTTP Fields value types
+title: Accessing the HTTP field values
 order: 4
 ---
 
-# Structured Fields Values
+# HTTP Fields Values
 
 ## Value type conversion to PHP
 
@@ -121,4 +121,79 @@ $displayString->type(); // returns Type::DisplayString
 > Values are not directly accessible. They can only be retrieved from an Item
 > Data type.
 
-← [Parsing and Serializing](02-parsing-serializing.md)  |  [Item](04-item.md) →
+## The Item Data Type
+
+This is the structure from which you will be able to access the actual field content.
+
+### Item value
+
+The eight (8) defined value types are all attached to an `Item` object where their value and
+type are accessible using the following methods:
+
+```php
+use Bakame\Http\StructuredFields\Item;
+
+$item = Item::fromHttpValue('@1234567890');
+$item->type();  // return Type::Date;
+$item->value()  // return the equivalent to DateTimeImmutable('@1234567890');
+```
+
+The `Item` value object exposes the following named constructors to instantiate
+bare items (ie: item without parameters attached to them).
+
+```php
+use Bakame\Http\StructuredFields\Byte;
+use Bakame\Http\StructuredFields\Item;
+use Bakame\Http\StructuredFields\Token;
+
+Item:new(DateTimeInterface|Byte|Token|DisplayString|string|int|array|float|bool $value): self
+Item:tryNew(mixed $value): ?self
+Item::fromDecodedByteSequence(Stringable|string $value): self;
+Item::fromEncodedDisplayString(Stringable|string $value): self;
+Item::fromDecodedDisplayString(Stringable|string $value): self;
+Item::fromEncodedByteSequence(Stringable|string $value): self;
+Item::fromToken(Stringable|string $value): self;
+Item::fromString(Stringable|string $value): self;
+Item::fromDate(DateTimeInterface $datetime): self;
+Item::fromDateFormat(string $format, string $datetime): self;
+Item::fromDateString(string $datetime, DateTimeZone|string|null $timezone = null): self;
+Item::fromTimestamp(int $value): self;
+Item::fromDecimal(int|float $value): self;
+Item::fromInteger(int|float $value): self;
+Item::true(): self;
+Item::false(): self;
+```
+
+To update the `Item` instance value, use the `withValue` method:
+
+```php
+use Bakame\Http\StructuredFields\Item;
+
+Item::withValue(DateTimeInterface|Byte|Token|DisplayString|string|int|float|bool $value): static
+```
+
+### Item Parameters
+
+Items can have parameters attached to them. A parameter is a bere item, an item which can not have parameters
+attach to it, to avoid recursive behaviour. Parameters are grouped in an ordered map container called `Parameters`.
+They can be accessed by their indices **but also** by their required key attached to them.
+
+```php
+
+$item = Item::fromHttpValue('application/xml;q=0.9;foobar');
+$item->value()->toString(); // returns 'application/xhtml+xml'
+$item->parameterByName(name: 'q', default: 1.0); // returns 1.0 if the parameter is not defined
+$item->parameterByIndex(index: 1, default: ['toto', false]); // returns ['foobar', true] because there's a parameter at index 1
+$item->parameters(); // returns a Parameters instance.
+```
+
+By default, you can access the member `Item` of a parameters using the following methods:
+
+- `Item::parameters` returns a `Parameters` instance;
+- `Item::parameterByName` returns the value of the bare item instance attached to the supplied `name`;
+- `Item::parameterByIndex` returns the value of the bare item instance attached to the supplied `index`;
+
+It is possible to alter and modify the `Parameters` attached to an `Item` but this section
+will be explored in the next section about the containers.
+
+← [Parsing and Serializing](02-parsing-serializing.md)  |  [Containers](04-containers.md) →

docs/05-containers.md renamed to docs/04-containers.md

@@ -428,4 +428,4 @@ echo InnerList::new('foo', 'bar')
 // ("foo" "bar");expire=@1681538756;path="/";max-age=2500
 ```
 
-← [Item](04-item.md)  |  [Validation](06-validation.md) →
+← [Accessing Field Values](03-field-values.md)  |  [Validation](05-validation) →

docs/04-item.md

@@ -432,4 +432,4 @@ class it becomes easier to reuse it to validate your data.
 
 To show how this can be achieved you can check the codebase from [HTTP Cache Status](https://github.com/bakame-php/http-cache-status)
 
-← [Containers](05-containers.md)  | [Extending the package functionalities](07-extensions.md)
+← [Containers](04-containers.md)  | [Extending the package functionalities](07-extensions.md)

docs/06-validation.md renamed to docs/05-validation.md

@@ -1,12 +1,22 @@
 ---
-title: Interacting with PHP ecosystem
+title: Interacting with the PHP ecosystem
 order: 8
 ---
 
-# Interacting with PHP ecosystem
+# Interacting with the PHP ecosystem
+
+## Everything is final
+
+As a rule of thumb all the classes from this package are final and immutable and
+expose no particular interface.
+
+The reason is to ensure that in any situation the RFC is being respected. The contract
+is between the RFC and your code the package only acts as a link between both parties.
+
+## DataTypes are Stringable
 
 All Datatypes expose the `Stringable` interface while it is recommended to use
-the `toHttpValue` method for better granularity. Supporting the `Stringable`
+the `toHttpValue` method for better granularity but supporting the `Stringable`
 interface allows the package to easily interface with packages and frameworks
 which expects a string or a stringable object when adding or updating
 HTTP field values.
@@ -18,17 +28,10 @@ $container->toHttpValue(); // returns '(:SGVsbG8gV29ybGQ=: 42.0 42)'
 echo $container;           // returns '(:SGVsbG8gV29ybGQ=: 42.0 42)' 
 ```
 
-## Everything is final
-
-As a rule of thumb all the classes from this package are final and immutable and
-expose no particular interface.
-
-The reason is to ensure that in any situation the RFC is being respected. The contract
-is between the RFC and your code the package only acts as a link between both parties.
-
 ## Closed for extension opened for composition
 
-On the other hand to allow composition the package does expose the `StructuredFieldProvider` interface.
+While the DataTypes can not be extended, to allow composition, the package exposes
+the `StructuredFieldProvider` interface.
 
 ```php
 interface StructuredFieldProvider
@@ -40,11 +43,11 @@ interface StructuredFieldProvider
 }
 ```
 
-This interface should return one of the DataType class and this is the interface that needs
-to be implemented. All the containers are able to work with a `StructuredFieldProvider`.
+This interface should return one of the DataType instance and all the containers are able to work
+with object that implement the interface.
 
-Imagine you have an `AcceptHeaderItem` class, and you want to take advantage of the package. You
-only have to implement the `StructuredFieldProvider`. Once done, your class will be able to
+As an example, imagine you have an `AcceptHeaderItem` class, and you want to take advantage of the package.
+You will have to implement the `StructuredFieldProvider`. Once done, your class will be able to
 work with the `OuterList` class.
 
 ```php
@@ -91,11 +94,11 @@ echo OuterList::new($json, $csv);
 ```
 
 In the example provided we added the interface on the class itself but of course you are free to use
-a different approach, as long as you end up have a class that implements the `StructuredFieldProvider`
+a different approach, as long as you end up having a class that implements the `StructuredFieldProvider`
 contract.
 
 To show how this can be achieved you can check the codebase from [HTTP Cache Status](https://github.com/bakame-php/http-cache-status)
 which uses the interface. Of note by using this interface you can completely hide the presence of 
 this package to your end users if needed.
 
-← [Validation](06-validation.md) 
+← [Validation](05-validation.md)