Adding comments and cleaning up code

lib/Proem/Util/Opt/Option.php

@@ -43,42 +43,78 @@ class Option
     private $unless             = [];
     private $type_validators    = [];
 
-
-
+    /**
+     * Instantiate the Option object
+     *
+     * @param mixed $value
+     *
+     * We use the __FILE__ constant as a default here because
+     * it is unlikely to ever be used as an actual value
+     */
     public function __construct($value = __FILE__) {
         $this->value = $value;
 
         $this
-            ->addValidator('array',     function($value) { return is_array($value); })
-            ->addValidator('bool',      function($value) { return is_bool($value); })
-            ->addValidator('float',     function($value) { return is_float($value); })
-            ->addValidator('int',       function($value) { return is_int($value); })
-            ->addValidator('callable',  function($value) { return is_callable($value); })
-            ->addValidator('object',    function($value) { return is_object($value); });
+            ->addTypeValidator('array',     function($value) { return is_array($value); })
+            ->addTypeValidator('bool',      function($value) { return is_bool($value); })
+            ->addTypeValidator('float',     function($value) { return is_float($value); })
+            ->addTypeValidator('int',       function($value) { return is_int($value); })
+            ->addTypeValidator('callable',  function($value) { return is_callable($value); })
+            ->addTypeValidator('object',    function($value) { return is_object($value); });
     }
 
-    public function addValidator($type, $callback, $override = false)
+    /**
+     * Add a custom Type validator or override an existing validator
+     *
+     * @param string $type
+     * @param function $callback
+     * @param bool $override
+     * @return Option
+     */
+    public function addTypeValidator($type, $callback, $override = false)
     {
         if (!isset($this->type_validators[$type]) || $override) {
             $this->type_validators[$type] = $callback;
         }
         return $this;
     }
 
+    /**
+     * Set the value of this Option object
+     *
+     * @param mixed $value
+     * @return Option
+     */
     public function setValue($value) {
         $this->value = $value;
         return $this;
     }
 
+    /**
+     * Get the value of this Option object
+     *
+     * @return mixed $this->value
+     */
     public function getValue() {
         return $this->value;
     }
 
+    /**
+     * Set this Option as required
+     *
+     * @return Option
+     */
     public function required() {
         $this->is_required = true;
         return $this;
     }
 
+    /**
+     * Disable this Option from being required if some other argument(s) has been provided
+     *
+     * @param string|array $options
+     * @return Option
+     */
     public function unless($options)
     {
         if (is_array($options)) {
@@ -89,25 +125,55 @@ public function unless($options)
         return $this;
     }
 
+    /**
+     * Force this Option value to be of a certain type
+     *
+     * Once specified, this Option's value will then be processed through
+     * an appropriate "type" validator.
+     *
+     * @param string $type
+     * @return Option
+     */
     public function type($type)
     {
         $this->is_type = $type;
         return $this;
     }
 
+    /**
+     * Force this Option's value to be an instance of a particular object
+     *
+     * @param string $object A string representation of a class name
+     * @return Option
+     */
     public function object($object)
     {
         $this->is_object = $object;
         return $this;
     }
 
+    /**
+     * Force this Option's value to be a string representation of a
+     * particular class or subclass
+     *
+     * @param string $class
+     * @return Option
+     */
     public function classof($class)
     {
         $this->is_classof = $class;
         return $this;
     }
 
-    public function validate($options) {
+    /**
+     * Validate this Option's value according to specified rules.
+     *
+     * @param array $options An array of all options that may have been processed alongside this Option
+     * @throws \InvalidArgumentException
+     * @throws \RuntimeException
+     * @return true
+     */
+    public function validate($options = []) {
         if ($this->unless) {
             $keys = array_keys($options);
             if (!count(array_diff($this->unless, array_keys($options)))) {

lib/Proem/Util/Opt/Options.php

@@ -35,24 +35,33 @@
  */
 trait Options
 {
+    /**
+     * Merge default Options with user supplied arguments applying validation in the process.
+     *
+     * @param array $default Default Options
+     * @param array $options User supplied Options
+     * @return array $defaults End result of merging default options with validated user options
+     */
     public function setOptions($defaults, $options)
     {
         foreach ($options as $key => $value) {
-            if (isset($defaults[$key])) {
+            if (isset($defaults[$key]) && ($defaults[$key] instanceof Option)) {
                 $defaults[$key]->setValue($value);
             } else {
                 $defaults[$key] = new Option($value);
             }
         }
 
         foreach ($defaults as $key => $value) {
-            try {
-                $value->validate($options);
-                $defaults[$key] = $value->getValue();
-            } catch (\InvalidArgumentException $e) {
-                throw new \InvalidArgumentException($key . $e->getMessage());
-            } catch (\RuntimeException $e) {
-                throw new \RuntimeException($e->getMessage());
+            if ($value instanceof Option) {
+                try {
+                    $value->validate($options);
+                    $defaults[$key] = $value->getValue();
+                } catch (\InvalidArgumentException $e) {
+                    throw new \InvalidArgumentException($key . $e->getMessage());
+                } catch (\RuntimeException $e) {
+                    throw new \RuntimeException($e->getMessage());
+                }
             }
         }
         return (object) $defaults;

tests/lib/Proem/Tests/Util/Opt/Fixtures/OptionFixture2.php

@@ -39,7 +39,7 @@ public function __construct(array $options = array())
             'foo'           => (new Option())->required()->unless('bar'),
             'obj'           => (new Option())->classof('Proem\Proem'),
             'emptytest'     => (new Option())->object('Proem\Proem'),
-            'custom-arg'    => (new Option())->addValidator('custom', function($value) { return preg_match('/[a-z]/', $value); })->type('custom')
+            'custom-arg'    => (new Option())->addTypeValidator('custom', function($value) { return preg_match('/[a-z]/', $value); })->type('custom')
         ], $options);
     }