From 57f24766429b5d95ff72d1e3d492b8b5a907849f Mon Sep 17 00:00:00 2001
From: Brandon Lamb <brandon@brandonlamb.com>
Date: Mon, 26 May 2014 13:37:13 -0700
Subject: [PATCH] Update docblocks, consistency/missing types, etc

---
 src/Valitron/Validator.php | 233 +++++++++++++++++++++++--------------
 1 file changed, 144 insertions(+), 89 deletions(-)

diff --git a/src/Valitron/Validator.php b/src/Valitron/Validator.php
index bd669cb..8463d7b 100644
--- a/src/Valitron/Validator.php
+++ b/src/Valitron/Validator.php
@@ -1,4 +1,5 @@
 <?php
+
 namespace Valitron;
 
 use InvalidArgumentException;
@@ -14,22 +15,64 @@ use InvalidArgumentException;
  */
 class Validator
 {
-    protected $_fields = array();
-    protected $_errors = array();
-    protected $_validations = array();
-    protected $_labels = array();
-
-    protected static $_lang;
-    protected static $_langDir;
-    protected static $_rules = array();
-    protected static $_ruleMessages = array();
-
+    /**
+     * @var string
+     */
     const ERROR_DEFAULT = 'Invalid';
 
+    /**
+     * @var array
+     */
+    protected $_fields = array();
+
+    /**
+     * @var array
+     */
+    protected $_errors = array();
+
+    /**
+     * @var array
+     */
+    protected $_validations = array();
+
+    /**
+     * @var array
+     */
+    protected $_labels = array();
+
+    /**
+     * @var string
+     */
+    protected static $_lang;
+
+    /**
+     * @var string
+     */
+    protected static $_langDir;
+
+    /**
+     * @var array
+     */
+    protected static $_rules = array();
+
+    /**
+     * @var array
+     */
+    protected static $_ruleMessages = array();
+
+    /**
+     * @var array
+     */
     protected $validUrlPrefixes = array('http://', 'https://', 'ftp://');
 
     /**
-     *  Setup validation
+     * Setup validation
+     *
+     * @param array $data
+     * @param array $fields
+     * @param string $lang
+     * @param string $langDir
+     * @throws \InvalidArgumentException
      */
     public function __construct($data, $fields = array(), $lang = null, $langDir = null)
     {
@@ -58,6 +101,9 @@ class Validator
 
     /**
      * Get/set language to use for validation messages
+     *
+     * @param string $Lang
+     * @return string
      */
     public static function lang($lang = null)
     {
@@ -69,6 +115,9 @@ class Validator
 
     /**
      * Get/set language file path
+     *
+     * @param string $dir
+     * @return string
      */
     public static function langDir($dir = null)
     {
@@ -81,8 +130,8 @@ class Validator
     /**
      * Required field validator
      *
-     * @param $field
-     * @param $value
+     * @param string $field
+     * @param mixed $value
      * @return bool
      */
     protected function validateRequired($field, $value)
@@ -98,8 +147,8 @@ class Validator
     /**
      * Validate that two values match
      *
-     * @param  string $field
-     * @param  mixed $value
+     * @param string $field
+     * @param mixed $value
      * @param array $params
      * @internal param array $fields
      * @return bool
@@ -113,8 +162,8 @@ class Validator
     /**
      * Validate that a field is different from another field
      *
-     * @param  string $field
-     * @param  mixed $value
+     * @param string $field
+     * @param mixed $value
      * @param array $params
      * @internal param array $fields
      * @return bool
@@ -130,8 +179,8 @@ class Validator
      *
      * This validation rule implies the field is "required"
      *
-     * @param  string  $field
-     * @param  mixed   $value
+     * @param string $field
+     * @param mixed $value
      * @return bool
      */
     protected function validateAccepted($field, $value)
@@ -143,8 +192,8 @@ class Validator
     /**
      * Validate that a field is numeric
      *
-     * @param  string  $field
-     * @param  mixed   $value
+     * @param string $field
+     * @param mixed $value
      * @return bool
      */
     protected function validateNumeric($field, $value)
@@ -155,8 +204,8 @@ class Validator
     /**
      * Validate that a field is an integer
      *
-     * @param  string  $field
-     * @param  mixed   $value
+     * @param string $field
+     * @param mixed $value
      * @return bool
      */
     protected function validateInteger($field, $value)
@@ -167,9 +216,9 @@ class Validator
     /**
      * Validate the length of a string
      *
-     * @param  string $field
-     * @param  mixed $value
-     * @param $params
+     * @param string $field
+     * @param mixed $value
+     * @param array $params
      * @internal param array $fields
      * @return bool
      */
@@ -188,9 +237,8 @@ class Validator
      * Validate the length of a string (between)
      *
      * @param string $field
-     * @param mixed  $value
-     * @param array  $params
-     *
+     * @param mixed $value
+     * @param array $params
      * @return boolean
      */
     protected function validateLengthBetween($field, $value, $params)
@@ -203,8 +251,8 @@ class Validator
      * Validate the length of a string (min)
      *
      * @param string $field
-     * @param mixed  $value
-     * @param array  $params
+     * @param mixed $value
+     * @param array $params
      *
      * @return boolean
      */
@@ -217,8 +265,8 @@ class Validator
      * Validate the length of a string (max)
      *
      * @param string $field
-     * @param mixed  $value
-     * @param array  $params
+     * @param mixed $value
+     * @param array $params
      *
      * @return boolean
      */
@@ -230,7 +278,7 @@ class Validator
     /**
      * Get the length of a string
      *
-     * @param  string  $value
+     * @param string $value
      * @return int
      */
     protected function stringLength($value)
@@ -244,9 +292,9 @@ class Validator
     /**
      * Validate the size of a field is greater than a minimum value.
      *
-     * @param  string $field
-     * @param  mixed $value
-     * @param $params
+     * @param string $field
+     * @param mixed $value
+     * @param array $params
      * @internal param array $fields
      * @return bool
      */
@@ -258,9 +306,9 @@ class Validator
     /**
      * Validate the size of a field is less than a maximum value
      *
-     * @param  string $field
-     * @param  mixed $value
-     * @param $params
+     * @param string $field
+     * @param mixed $value
+     * @param array $params
      * @internal param array $fields
      * @return bool
      */
@@ -272,9 +320,9 @@ class Validator
     /**
      * Validate a field is contained within a list of values
      *
-     * @param  string $field
-     * @param  mixed $value
-     * @param $params
+     * @param string $field
+     * @param mixed $value
+     * @param array $params
      * @internal param array $fields
      * @return bool
      */
@@ -290,9 +338,9 @@ class Validator
     /**
      * Validate a field is not contained within a list of values
      *
-     * @param  string $field
-     * @param  mixed $value
-     * @param $params
+     * @param string $field
+     * @param mixed $value
+     * @param array $params
      * @internal param array $fields
      * @return bool
      */
@@ -304,9 +352,9 @@ class Validator
     /**
      * Validate a field contains a given string
      *
-     * @param  string $field
-     * @param  mixed  $value
-     * @param  array  $params
+     * @param string $field
+     * @param mixed $value
+     * @param array $params
      * @return bool
      */
     protected function validateContains($field, $value, $params)
@@ -323,8 +371,8 @@ class Validator
     /**
      * Validate that a field is a valid IP address
      *
-     * @param  string  $field
-     * @param  mixed   $value
+     * @param string $field
+     * @param mixed $value
      * @return bool
      */
     protected function validateIp($field, $value)
@@ -335,8 +383,8 @@ class Validator
     /**
      * Validate that a field is a valid e-mail address
      *
-     * @param  string  $field
-     * @param  mixed   $value
+     * @param string $field
+     * @param mixed $value
      * @return bool
      */
     protected function validateEmail($field, $value)
@@ -347,8 +395,8 @@ class Validator
     /**
      * Validate that a field is a valid URL by syntax
      *
-     * @param  string  $field
-     * @param  mixed   $value
+     * @param string $field
+     * @param mixed $value
      * @return bool
      */
     protected function validateUrl($field, $value)
@@ -364,8 +412,8 @@ class Validator
     /**
      * Validate that a field is an active URL by verifying DNS record
      *
-     * @param  string  $field
-     * @param  mixed   $value
+     * @param string $field
+     * @param mixed $value
      * @return bool
      */
     protected function validateUrlActive($field, $value)
@@ -383,8 +431,8 @@ class Validator
     /**
      * Validate that a field contains only alphabetic characters
      *
-     * @param  string  $field
-     * @param  mixed   $value
+     * @param string $field
+     * @param mixed $value
      * @return bool
      */
     protected function validateAlpha($field, $value)
@@ -395,8 +443,8 @@ class Validator
     /**
      * Validate that a field contains only alpha-numeric characters
      *
-     * @param  string  $field
-     * @param  mixed   $value
+     * @param string $field
+     * @param mixed $value
      * @return bool
      */
     protected function validateAlphaNum($field, $value)
@@ -407,8 +455,8 @@ class Validator
     /**
      * Validate that a field contains only alpha-numeric characters, dashes, and underscores
      *
-     * @param  string  $field
-     * @param  mixed   $value
+     * @param string $field
+     * @param mixed $value
      * @return bool
      */
     protected function validateSlug($field, $value)
@@ -419,9 +467,9 @@ class Validator
     /**
      * Validate that a field passes a regular expression check
      *
-     * @param  string $field
-     * @param  mixed $value
-     * @param $params
+     * @param string $field
+     * @param mixed $value
+     * @param array $params
      * @return bool
      */
     protected function validateRegex($field, $value, $params)
@@ -432,8 +480,8 @@ class Validator
     /**
      * Validate that a field is a valid date
      *
-     * @param  string  $field
-     * @param  mixed   $value
+     * @param string $field
+     * @param mixed $value
      * @return bool
      */
     protected function validateDate($field, $value)
@@ -444,9 +492,9 @@ class Validator
     /**
      * Validate that a field matches a date format
      *
-     * @param  string $field
-     * @param  mixed $value
-     * @param $params
+     * @param string $field
+     * @param mixed $value
+     * @param array $params
      * @internal param array $fields
      * @return bool
      */
@@ -460,9 +508,9 @@ class Validator
     /**
      * Validate the date is before a given date
      *
-     * @param  string $field
-     * @param  mixed $value
-     * @param $params
+     * @param string $field
+     * @param mixed $value
+     * @param array $params
      * @internal param array $fields
      * @return bool
      */
@@ -476,9 +524,9 @@ class Validator
     /**
      * Validate the date is after a given date
      *
-     * @param  string $field
-     * @param  mixed $value
-     * @param $params
+     * @param string $field
+     * @param mixed $value
+     * @param array $params
      * @internal param array $fields
      * @return bool
      */
@@ -492,8 +540,8 @@ class Validator
     /**
      * Validate that a field contains a boolean.
      *
-     * @param  string  $field
-     * @param  mixed   $value
+     * @param string $field
+     * @param mixed $value
      * @return bool
      */
     protected function validateBoolean($field, $value)
@@ -505,8 +553,8 @@ class Validator
      * Validate that a field contains a valid credit card
      * optionally filtered by an array
      *
-     * @param string  $field
-     * @param string $value
+     * @param string $field
+     * @param mixed $value
      * @param array $params
      * @return bool
      */
@@ -613,6 +661,8 @@ class Validator
 
     /**
      *  Get array of fields and data
+     *
+     * @return array
      */
     public function data()
     {
@@ -636,8 +686,8 @@ class Validator
     /**
      * Add an error to error messages array
      *
-     * @param $field
-     * @param $msg
+     * @param string $field
+     * @param string $msg
      * @param array $params
      */
     public function error($field, $msg, array $params = array())
@@ -742,7 +792,7 @@ class Validator
      * Register new validation rule callback
      *
      * @param string $name
-     * @param $callback
+     * @param mixed $callback
      * @param string $message
      * @throws \InvalidArgumentException
      */
@@ -758,6 +808,10 @@ class Validator
 
     /**
      * Convenience method to add a single validation rule
+     *
+     * @param string $fule
+     * @param array $fields
+     * @return $this
      */
     public function rule($rule, $fields)
     {
@@ -784,7 +838,7 @@ class Validator
     }
 
     /**
-     * @param $value
+     * @param string $value
      * @internal param array $labels
      * @return $this
      */
@@ -798,7 +852,7 @@ class Validator
 
     /**
      * @param array $labels
-     * @return $this
+     * @return string
      */
     public function labels($labels = array())
     {
@@ -807,9 +861,9 @@ class Validator
     }
 
     /**
-     * @param $field
-     * @param $msg
-     * @param $params
+     * @param string $field
+     * @param string $msg
+     * @param array $params
      * @return array
      */
     private function checkAndSetLabel($field, $msg, $params)
@@ -835,6 +889,7 @@ class Validator
 
     /**
      * Convenience method to add multiple validation rules with an array
+     *
      * @param array $rules
      */
     public function rules($rules)