Update documentation v2

Author: nyamsprod

docs/05-containers.md

@@ -100,7 +100,7 @@ with the changes applied and leave the original instance unchanged.
 
 ### Ordered Maps
 
-The `Dictionary` and `Parameters` are ordered map instances. They can be built using their keys with an
+The `Dictionary` and `Parameters` are ordered map instances. They can be built using their names with an
 associative iterable structure as shown below
 
 ```php
@@ -142,7 +142,7 @@ $map->add(string $name, $value): static;
 $map->append(string $name, $value): static;
 $map->prepend(string $name, $value): static;
 $map->mergeAssociative(...$others): static;
-$map->removeByKeys(string ...$names): static;
+$map->removeByNames(string ...$names): static;
 ```
 
 As shown below:
@@ -210,17 +210,17 @@ echo $value;                //b=?0, a=(bar "42" 42 42.0), c=@1671800423
 ```
 
 > [!CAUTION]
-> on duplicate `keys` pair values are merged as per RFC logic.
+> on duplicate `names` pair values are merged as per RFC logic.
 
-The following methods `removeByIndices` and/or `removeByKeys` allow removing members
-per indices or per keys.
+The following methods `removeByIndices` and/or `removeByNames` allow removing members
+per indices or per names.
 
 ```php
 use Bakame\Http\StructuredFields\Parameters;
 
 $field = Parameters::fromHttpValue(';expire=@1681504328;path="/";max-age=2500;secure;httponly=?0;samesite=lax');
 echo $field->removeByIndices(4, 2, 0)->toHttpValue();                      // returns ;path="/";secure;samesite=lax
-echo $field->removeByKeys('expire', 'httponly', 'max-age')->toHttpValue(); // returns ;path="/";secure;samesite=lax
+echo $field->removeByNames('expire', 'httponly', 'max-age')->toHttpValue(); // returns ;path="/";secure;samesite=lax
 ```
 
 ### Automatic conversion
@@ -387,14 +387,14 @@ You can attach and update the associated `Parameters` instance using the followi
 $field->addParameter(string $name, mixed $value): static;
 $field->appendParameter(string $name, mixed $value): static;
 $field->prependParameter(string $name, mixed $value): static;
-$field->withoutParameters(string ...$keys): static; // this method is deprecated as of version 1.1 use withoutParametersByKeys instead
+$field->withoutParameters(string ...$names): static; // this method is deprecated as of version 1.1 use withoutParametersByKeys instead
 $field->withoutAnyParameter(): static;
 $field->withParameters(Parameters $parameters): static;
 $field->pushParameters(array ...$pairs): static
 $field->unshiftParameters(array ...$pairs): static
 $field->insertParameters(int $index, array ...$pairs): static
 $field->replaceParameter(int $index, array $pair): static
-$field->withoutParametersByKeys(string ...$keys): static
+$field->withoutParametersByNames(string ...$names): static
 $field->withoutParametersByIndices(int ...$indices): static
 ```
 

docs/06-validation.md

@@ -137,26 +137,26 @@ $value = $member
 
 ### Validating the Item parameters.
 
-### Checking for allowed keys
+### Checking for allowed names
 
 Before validating the content of the `Parameters` container we need to make
-sure the container contains the proper data. That all the allowed keys are
-present. To do so we can use the `Parameters::allowedKeys` method. This
-method expects a list of keys. If other keys not present in the
+sure the container contains the proper data. That all the allowed names are
+present. To do so we can use the `Parameters::allowedNames` method. This
+method expects a list of names. If other names not present in the
 list are found in the container the method will return `false`. If we
-go back to our definition. We know that the allowed parameters keys attached
+go back to our definition. We know that the allowed parameters names attached
 to the item are: `location`, `longitude`, `latitude` and `date`
 
 ```php
 use Bakame\Http\StructuredFields\Validation\Violation;
 
-if (!$member->parameters()->allowedKeys(['location', 'longitude', 'latitude', 'date'])) {
-    throw new Violation('The parameters contains extra keys that are not allowed.');
+if (!$member->parameters()->allowedNames(['location', 'longitude', 'latitude', 'date'])) {
+    throw new Violation('The parameters contains extra names that are not allowed.');
 }
 ```
 
 > [!TIP]
-> The `Dictionary` class also exposes an `allowedKeys` method which behave the same way.
+> The `Dictionary` class also exposes an `allowedNames` method which behave the same way.
 
 > [!WARNING]
 > if the parameters container is empty no error will be triggered
@@ -208,13 +208,13 @@ all the criteria.
 Going back to the HTTP field definitions we can translate the requirements and create the
 following `ParametersValidator`.
 
-We need to make sure about the allowed keys for that. the class has a `filterByCriteria` which
+We need to make sure about the allowed names for that. the class has a `filterByCriteria` which
 expects the `Parameters` container as its sole argument.
 
 ```php
 $parametersValidator = ParametersValidator::new()
     ->filterByCriteria(function (Parameters $parameters): bool|string {
-        return $parameters->allowedKeys(['location', 'longitude', 'latitude', 'date']);
+        return $parameters->allowedNames(['location', 'longitude', 'latitude', 'date']);
     });
 ```
 
@@ -228,7 +228,7 @@ we did earlier we end up with the following entries.
 ```php
 use Bakame\Http\StructuredFields\Type;
 
-$parametersValidator = ->filterByKeys([
+$parametersValidator = ->filterByNames([
         'longitude' => [
             'validate' => function (mixed $value) {
                  if (!Type::Decimal->supports($value)) {
@@ -242,7 +242,7 @@ $parametersValidator = ->filterByKeys([
     ]);
 ```
 
-We can do the same for all the other keys, the available parameters are:
+We can do the same for all the other names, the available parameters are:
 - `validate`: the callback used for validation; `null` by default
 - `required`: a boolean telling whether the parameter presence is required; `false` by default
 - `default`: the default value if the parameter is optional; `null` by default.
@@ -329,7 +329,7 @@ if ($validation->isSucces()) {
 > [!NOTE]
 > If we only use the `filterByCriteria` method the full parameter data is returned.
 
- A `filterByIndices` method exists and behave exactly as the `filterByKeys` method.
+ A `filterByIndices` method exists and behave exactly as the `filterByNames` method.
 There are two differences when it is used:
 
 - The callback parameters are different (they match those of `parameterByIndex`)

docs/07-extensions.md

@@ -23,14 +23,8 @@ echo $container;           // returns '(:SGVsbG8gV29ybGQ=: 42.0 42)'
 As a rule of thumb all the classes from this package are final and immutable and
 expose no particular interface.
 
-> [!IMPORTANT]
-> The `StructuredField` interface should be seen as an internal implementation detail 
-> and should not be implemented outside the package. While PHP does not prohibit such 
-> action, **you MUST NOT implement the `StructuredField` interface.**
-
-The reason for disallowing the `StructuredField` interface is simple. We want 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.
+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
 
@@ -49,8 +43,8 @@ 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`.
 
-Imagine you have an `AcceptHeaderItem` class and you want to take advantage of the package. You
-only have to implemente the `StructuredFieldProvider`. Once done, your class will be able to
+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
 work with the `OuterList` class.
 
 ```php

src/Item.php

@@ -43,7 +43,7 @@ public static function fromRfc8941(Stringable|string $httpValue): self
 
     /**
      * Returns a new instance from an HTTP Header or Trailer value string
-     * in compliance with RFC8941.
+     * in compliance with a published RFC.
      *
      * @see https://www.rfc-editor.org/rfc/rfc9651.html#section-3.3
      *