Update inline documentation

src/ArrayDeserializer.php

@@ -4,22 +4,31 @@
 namespace Stratadox\Deserializer;
 
 /**
- * Array deserializer.
+ * Deserializes the input array into collection arrays, serving as null object
+ * for collection deserializers.
  *
  * @author Stratadox
+ * @license MIT
  */
 final class ArrayDeserializer implements DeserializesCollections
 {
+    /**
+     * Makes a new deserializer for arrays.
+     *
+     * @return DeserializesCollections The array deserializer.
+     */
     public static function make(): DeserializesCollections
     {
         return new ArrayDeserializer;
     }
 
+    /** @inheritdoc */
     public function from(array $input): iterable
     {
         return $input;
     }
 
+    /** @inheritdoc */
     public function typeFor(array $input): string
     {
         return 'array';

src/CollectionDeserializer.php

@@ -13,9 +13,10 @@
 use Stratadox\Instantiator\ProvidesInstances;
 
 /**
- * Collection object deserializer.
+ * Deserializes the input array into collection objects.
  *
  * @author Stratadox
+ * @license MIT
  */
 final class CollectionDeserializer implements DeserializesCollections
 {

src/Condition/AreOfList.php

@@ -8,15 +8,27 @@
 use Stratadox\Specification\Contract\Specifies;
 use Stratadox\Specification\Specifying;
 
+/**
+ * Condition that accepts list typed input.
+ *
+ * @author Stratadox
+ * @license MIT
+ */
 final class AreOfList implements Specifies
 {
     use Specifying;
 
+    /**
+     * Produces a condition that accepts list type input.
+     *
+     * @return Specifies The type enforcing condition.
+     */
     public static function type(): Specifies
     {
         return new self;
     }
 
+    /** @inheritdoc */
     public function isSatisfiedBy($input): bool
     {
         return is_array($input)

src/Condition/AreOfType.php

@@ -7,6 +7,12 @@
 use Stratadox\Specification\Contract\Specifies;
 use Stratadox\Specification\Specifying;
 
+/**
+ * Condition that accepts a specific input type.
+ *
+ * @author Stratadox
+ * @license MIT
+ */
 final class AreOfType implements Specifies
 {
     use Specifying;
@@ -18,21 +24,37 @@ private function __construct(string $expectation)
         $this->expectation = $expectation;
     }
 
+    /**
+     * Produces a condition that accepts boolean type input.
+     *
+     * @return Specifies The type enforcing condition.
+     */
     public static function boolean(): Specifies
     {
         return new AreOfType('boolean');
     }
 
+    /**
+     * Produces a condition that accepts integer type input.
+     *
+     * @return Specifies The type enforcing condition.
+     */
     public static function integer(): Specifies
     {
         return new AreOfType('integer');
     }
 
+    /**
+     * Produces a condition that accepts string type input.
+     *
+     * @return Specifies The type enforcing condition.
+     */
     public static function string(): Specifies
     {
         return new AreOfType('string');
     }
 
+    /** @inheritdoc */
     public function isSatisfiedBy($input): bool
     {
         return gettype($input) === $this->expectation;

src/Condition/ConsistOfItems.php

@@ -8,22 +8,37 @@
 use Stratadox\Specification\Contract\Specifies;
 use Stratadox\Specification\Specifying;
 
+/**
+ * Condition that accepts data where all items satisfy a condition.
+ *
+ * @author Stratadox
+ * @license MIT
+ */
 final class ConsistOfItems implements Specifies
 {
     use Specifying;
 
     private $condition;
 
-    public function __construct(Satisfiable $condition)
+    private function __construct(Satisfiable $condition)
     {
         $this->condition = $condition;
     }
 
+    /**
+     * Produces a condition that checks if all items satisfy a condition.
+     *
+     * @param Satisfiable $passingTheCondition The condition that must pass on
+     *                                         all items.
+     * @return Specifies                       The condition to apply on the
+     *                                         collection.
+     */
     public static function that(Satisfiable $passingTheCondition): Specifies
     {
         return new ConsistOfItems($passingTheCondition);
     }
 
+    /** @inheritdoc */
     public function isSatisfiedBy($input): bool
     {
         if (!is_iterable($input)) {

src/Condition/HaveTheDiscriminatorValue.php

@@ -6,6 +6,12 @@
 use Stratadox\Specification\Contract\Specifies;
 use Stratadox\Specification\Specifying;
 
+/**
+ * Condition that accepts data with a specific discriminator key and value.
+ *
+ * @author Stratadox
+ * @license MIT
+ */
 final class HaveTheDiscriminatorValue implements Specifies
 {
     use Specifying;
@@ -19,11 +25,19 @@ private function __construct(string $key, string $value)
         $this->value = $value;
     }
 
+    /**
+     * Produces a condition that checks a discriminator key/value combination.
+     *
+     * @param string $key   The discriminator key, for instance a column name.
+     * @param string $value The discriminator value to be triggered by.
+     * @return Specifies    The discriminating condition.
+     */
     public static function of(string $key, string $value): Specifies
     {
         return new self($key, $value);
     }
 
+    /** @inheritdoc */
     public function isSatisfiedBy($input): bool
     {
         return isset($input[$this->key])

src/FailedToDeserializeTheCollection.php

@@ -10,9 +10,22 @@
  * Notifies the client that the collection could not be deserialized.
  *
  * @author Stratadox
+ * @license MIT
  */
 final class FailedToDeserializeTheCollection extends RuntimeException implements CannotDeserialize
 {
+    /**
+     * Produces a deserialization exception to throw when a "foreign" exception
+     * was encountered during the collection deserialization process.
+     *
+     * Prepends the original exception message with additional information on
+     * what happened when the problem occurred.
+     *
+     * @param Throwable $exception The original exception that was caught while
+     *                             deserialization the collection.
+     * @return CannotDeserialize   The deserialization exception to throw in
+     *                             place of the encountered exception.
+     */
     public static function encountered(Throwable $exception): CannotDeserialize
     {
         return new FailedToDeserializeTheCollection(

src/FailedToDeserializeTheObject.php

@@ -10,9 +10,22 @@
  * Notifies the client that the object could not be deserialized.
  *
  * @author Stratadox
+ * @license MIT
  */
 final class FailedToDeserializeTheObject extends RuntimeException implements CannotDeserialize
 {
+    /**
+     * Produces a deserialization exception to throw when a "foreign" exception
+     * was encountered during the object deserialization process.
+     *
+     * Prepends the original exception message with additional information on
+     * what happened when the problem occurred.
+     *
+     * @param Throwable $exception The original exception that was caught while
+     *                             deserialization the object.
+     * @return CannotDeserialize   The deserialization exception to throw in
+     *                             place of the encountered exception.
+     */
     public static function encountered(Throwable $exception): CannotDeserialize
     {
         return new FailedToDeserializeTheObject(

src/ForDataSets.php

@@ -5,6 +5,15 @@
 
 use Stratadox\Specification\Contract\Satisfiable;
 
+/**
+ * Represents a deserialization option, consisting of a condition and a
+ * deserializer.
+ *
+ * The embedded deserializer is used for data sets that pass the condition.
+ *
+ * @author Stratadox
+ * @license MIT
+ */
 final class ForDataSets implements Option
 {
     private $condition;
@@ -16,6 +25,16 @@ private function __construct(Satisfiable $condition, Deserializes $deserialize)
         $this->deserialize = $deserialize;
     }
 
+    /**
+     * Produce an option for data sets that pass the condition.
+     *
+     * @param Satisfiable  $condition   The condition that must be satisfied by
+     *                                  the data set.
+     * @param Deserializes $deserialize The deserializer that will deserialize
+     *                                  satisfying data sets.
+     * @return Option                   The option object to supply to the
+     *                                  @see OneOfThese::deserializers() method.
+     */
     public static function that(Satisfiable $condition, Deserializes $deserialize): Option
     {
         return new ForDataSets($condition, $deserialize);

src/IllegalInputKey.php

@@ -8,12 +8,22 @@
 use function sprintf as withMessage;
 
 /**
- * NonNumericInputKey.
+ * Notifies the client that the input could not be accepted due to an illegal key.
  *
  * @author Stratadox
+ * @license MIT
  */
 final class IllegalInputKey extends InvalidArgumentException implements CannotDeserialize
 {
+    /**
+     * Produces a deserialization exception to throw when a collection input key
+     * is not considered valid.
+     *
+     * @param object $collection The collection that was assigned the illegal
+     *                           input key.
+     * @param string $key        The input key that was considered invalid.
+     * @return CannotDeserialize The deserialization exception to throw.
+     */
     public static function illegal(
         object $collection,
         string $key

src/NonIterableCollection.php

@@ -8,12 +8,21 @@
 use function sprintf as withMessage;
 
 /**
- * NonIterableCollection.
+ * Notifies the client that the result of the collection deserialization process
+ * resulted in output that is not iterable.
  *
  * @author Stratadox
+ * @license MIT
  */
 final class NonIterableCollection extends RuntimeException implements CannotDeserialize
 {
+    /**
+     * Produces a deserialization exception to throw when a collection turns out
+     * not to be iterable.
+     *
+     * @param object $collection The object that turns out not to be iterable.
+     * @return CannotDeserialize The deserialization exception to throw.
+     */
     public static function invalid(object $collection): CannotDeserialize
     {
         return new NonIterableCollection(withMessage(

src/ObjectDeserializer.php

@@ -12,6 +12,12 @@
 use Stratadox\Instantiator\Instantiator;
 use Stratadox\Instantiator\ProvidesInstances;
 
+/**
+ * Deserializes the input array into objects.
+ *
+ * @author Stratadox
+ * @license MIT
+ */
 final class ObjectDeserializer implements DeserializesObjects
 {
     private $make;

src/OneOfThese.php

@@ -5,18 +5,33 @@
 
 use Stratadox\ImmutableCollection\ImmutableCollection;
 
+/**
+ * Uses one of several deserialization options to deserialize the input array
+ * into objects.
+ *
+ * @author Stratadox
+ * @license MIT
+ */
 final class OneOfThese extends ImmutableCollection implements Deserializes
 {
     private function __construct(Option ...$options)
     {
         parent::__construct(...$options);
     }
 
+    /**
+     * Makes a new collection of deserialization options.
+     *
+     * @param Option ...$options The options to consider when deserializing an
+     *                           input array.
+     * @return Deserializes      The deserialization options container.
+     */
     public static function deserializers(Option ...$options): Deserializes
     {
         return new OneOfThese(...$options);
     }
 
+
     /** @inheritdoc */
     public function current(): Option
     {
@@ -35,6 +50,7 @@ public function typeFor(array $input): string
         return $this->wouldProduceFor($input, $this->optionFor($input));
     }
 
+
     /** @throws CannotDeserialize */
     private function makeFrom(array $input, Option $deserialize)
     {

src/UnacceptableInput.php

@@ -8,12 +8,20 @@
 use function sprintf as withMessage;
 
 /**
- * UnacceptableInput.
+ * Notifies the client that none of the hydration options accept the input.
  *
  * @author Stratadox
+ * @license MIT
  */
 final class UnacceptableInput extends InvalidArgumentException implements CannotDeserialize
 {
+    /**
+     * Produces a deserialization exception to throw when none of the options
+     * are satisfied by the input data.
+     *
+     * @param array $input       The input data that was not accepted.
+     * @return CannotDeserialize The deserialization exception to throw.
+     */
     public static function illegal(array $input): CannotDeserialize
     {
         return new UnacceptableInput(withMessage(