Expand documentation

src/Instruction/Call.php

@@ -12,19 +12,28 @@
 /**
  * Indicates that a closure should be called to hydrate this property.
  *
+ * @todo make final
  * @package Stratadox\Hydrate
  * @author Stratadox
  */
 class Call implements InstructsHowToMap
 {
     private $function;
 
+    // @todo make private
     public function __construct(Closure $function)
     {
         $this->function = $function;
     }
 
-    public static function the(Closure $function)
+    /**
+     * Create a closure call instruction for the property.
+     *
+     * @param Closure $function The anonymous function to call while hydrating
+     *                          this property.
+     * @return Call             The instruction object.
+     */
+    public static function the(Closure $function) : Call
     {
         return new Call($function);
     }

src/Instruction/Has.php

@@ -19,6 +19,13 @@ final class Has
 {
     private function __construct() {}
 
+    /**
+     * Define a has-one relationship with another class.
+     *
+     * @param string         $class The fully qualified class name.
+     * @param FindsKeys|null $key   The input array offset (optional)
+     * @return DefinesRelationships The relationship definition.
+     */
     public static function one(
         string $class,
         FindsKeys $key = null
@@ -27,6 +34,13 @@ public static function one(
         return HasOne::ofThe($class, $key);
     }
 
+    /**
+     * Define a has-many relationship with another class.
+     *
+     * @param string         $class The fully qualified class name.
+     * @param FindsKeys|null $key   The input array offset (optional)
+     * @return DefinesRelationships The relationship definition.
+     */
     public static function many(
         string $class,
         FindsKeys $key = null

src/Instruction/In.php

@@ -24,7 +24,13 @@ private function __construct($key)
         $this->key = $key;
     }
 
-    public static function key(string $key)
+    /**
+     * Indicates that the data for this property can be found in a different key.
+     *
+     * @param string $key The offset to use in the input array.
+     * @return In         The instruction object.
+     */
+    public static function key(string $key) : In
     {
         return new In($key);
     }

src/Instruction/Relation/Choose.php

@@ -25,6 +25,13 @@ private function __construct(MakesMap $class)
         $this->class = $class;
     }
 
+    /**
+     * Creates a new option to choose from.
+     *
+     * @param string $class     The fully qualified name of the class that can
+     *                          be chosen.
+     * @return RepresentsChoice The object representation of the choice.
+     */
     public static function the(string $class) : RepresentsChoice
     {
         return new Choose(Mapper::forThe($class));

src/Instruction/Relation/Relationship.php

@@ -14,6 +14,8 @@
 use Stratadox\Proxy\ProducesProxyLoaders;
 
 /**
+ * Defines a relationship with another class.
+ *
  * @package Stratadox\Hydrate
  * @author Stratadox
  */
@@ -23,15 +25,15 @@ abstract class Relationship implements DefinesRelationships
     protected $class;
     /** @var FindsKeys */
     protected $key;
-    /** @var ?string */
+    /** @var string|null */
     protected $container;
-    /** @var ?ProducesProxyLoaders */
+    /** @var ProducesProxyLoaders|null */
     protected $loader;
     /** @var bool */
     protected $shouldNest = false;
     /** @var InstructsHowToMap[] */
     protected $properties = [];
-    /** @var ?string */
+    /** @var string|null */
     protected $decisionKey;
     /** @var RepresentsChoice[] */
     protected $choices = [];
@@ -42,6 +44,13 @@ final protected function __construct(string $class, FindsKeys $key = null)
         $this->key = $key;
     }
 
+    /**
+     * Define a new relationship with another class.
+     *
+     * @param string         $class The fully qualified class name.
+     * @param FindsKeys|null $key   The input array offset (optional)
+     * @return DefinesRelationships The relationship definition.
+     */
     public static function ofThe(
         string $class,
         FindsKeys $key = null
@@ -92,11 +101,22 @@ public function selectBy(
         return $inst;
     }
 
+    /**
+     * Returns the key if one was provided, defaulting to the property name.
+     *
+     * @param string $property  The property name to use as fallback.
+     * @return string           The key to use as offset for the input data.
+     */
     protected function keyOr(string $property) : string
     {
         return $this->key ? $this->key->find() : $property;
     }
 
+    /**
+     * Produces a mapped hydrator according to the relationship configuration.
+     *
+     * @return Hydrates The hydrator for the relationship mapping.
+     */
     protected function hydrator() : Hydrates
     {
         if (isset($this->decisionKey)) {

src/NoContainerAvailable.php

@@ -15,6 +15,12 @@
  */
 final class NoContainerAvailable extends BadMethodCall implements InvalidMapperConfiguration
 {
+    /**
+     * Produce an exception for when there is no container defined for a class.
+     *.
+     * @param string $class The class that is missing a container.
+     * @return self         The exception object.
+     */
     public static function for(string $class) : self
     {
         return new self(sprintf(

src/NoLoaderAvailable.php

@@ -15,6 +15,12 @@
  */
 final class NoLoaderAvailable extends BadMethodCall implements InvalidMapperConfiguration
 {
+    /**
+     * Produce an exception for when there is no loader defined for a class.
+     *.
+     * @param string $class The class that is missing a loader.
+     * @return self         The exception object.
+     */
     public static function for(string $class) : self
     {
         return new self(sprintf(