Update the phpdoc for magic methods

src/Faker/Generator.php

@@ -5,7 +5,12 @@
 /**
  * @property string $name
  * @property string $firstName
+ * @property string $firstNameMale
+ * @property string $firstNameFemale
  * @property string $lastName
+ * @property string $title
+ * @property string $titleMale
+ * @property string $titleFemale
  *
  * @property string $citySuffix
  * @property string $streetSuffix
@@ -29,22 +34,29 @@
  *
  * @property string $creditCardType
  * @property string $creditCardNumber
- * @property string $creditCardExpirationDate
+ * @method string creditCardNumber($type = null, $formatted = false, $separator = '-')
+ * @property \DateTime $creditCardExpirationDate
  * @property string $creditCardExpirationDateString
  * @property string $creditCardDetails
  * @property string $bankAccountNumber
  * @property string $swiftBicNumber
  * @property string $vat
  *
  * @property string $word
- * @method string words()
- * @method string sentence()
- * @method string sentences()
- * @method string paragraph()
- * @method string paragraphs()
- * @method string text()
- *
- * @method string realText()
+ * @property string|array $words
+ * @method string|array words($nb = 3, $asText = false)
+ * @property string $sentence
+ * @method string sentence($nbWords = 6, $variableNbWords = true)
+ * @property string|array $sentences
+ * @method string|array sentences($nb = 3, $asText = false)
+ * @property string $paragraph
+ * @method string paragraph($nbSentences = 3, $variableNbSentences = true)
+ * @property string|array $paragraphs
+ * @method string|array paragraphs($nb = 3, $asText = false)
+ * @property string $text
+ * @method string text($maxNbChars = 200)
+ *
+ * @method string realText($maxNbChars = 200, $indexSize = 2)
  *
  * @property string $email
  * @property string $safeEmail
@@ -53,13 +65,17 @@
  * @property string $freeEmailDomain
  * @property string $safeEmailDomain
  * @property string $userName
+ * @property string $password
+ * @method string password($minLength = 6, $maxLength = 20)
  * @property string $domainName
  * @property string $domainWord
  * @property string $tld
  * @property string $url
+ * @property string $slug
+ * @method string slug($nbWords = 6, $variableNbWords = true)
  * @property string $ipv4
  * @property string $ipv6
- * @property string $internalIpv4
+ * @property string $localIpv4
  * @property string $macAddress
  *
  * @property int       $unixTime
@@ -78,52 +94,70 @@
  * @property int       $year
  * @property int       $century
  * @property string    $timezone
- * @method string date()
- * @method string time()
- * @method \DateTime dateTimeBetween()
+ * @method string date($format = 'Y-m-d', $max = 'now')
+ * @method string time($format = 'H:i:s', $max = 'now')
+ * @method \DateTime dateTimeBetween($startDate = '-30 years', $endDate = 'now')
  *
  * @property string $md5
  * @property string $sha1
  * @property string $sha256
  * @property string $locale
  * @property string $countryCode
+ * @property string $countryISOAlpha3
  * @property string $languageCode
- * @method boolean boolean()
+ * @property string $currencyCode
+ * @method boolean boolean($chanceOfGettingTrue = 50)
  *
  * @property int    $randomDigit
  * @property int    $randomDigitNotNull
  * @property string $randomLetter
- * @method int randomNumber()
- * @method mixed randomKey()
- * @method int numberBetween()
- * @method float randomFloat()
- * @method string randomElement()
- * @method string numerify()
- * @method string lexify()
- * @method string bothify()
- * @method string toLower()
- * @method string toUpper()
- * @method mixed optional()
- * @method UniqueGenerator unique()
- *
- * @method integer biasedNumberBetween()
- *
+ * @property string $randomAscii
+ * @method int randomNumber($nbDigits = null, $strict = false)
+ * @method int|string|null randomKey(array $array = array())
+ * @method int numberBetween($min = 0, $max = 2147483647)
+ * @method float randomFloat($nbMaxDecimals = null, $min = 0, $max = null)
+ * @method mixed randomElement(array $array = array('a', 'b', 'c'))
+ * @method array randomElements(array $array = array('a', 'b', 'c'), $count = 1)
+ * @method array|string shuffle($arg = '')
+ * @method array shuffleArray(array $array = array())
+ * @method string shuffleString($string = '', $encoding = 'UTF-8')
+ * @method string numerify($string = '###')
+ * @method string lexify($string = '????')
+ * @method string bothify($string = '## ??')
+ * @method string asciify($string = '****')
+ * @method string regexify($regex = '')
+ * @method string toLower($string = '')
+ * @method string toUpper($string = '')
+ * @method Generator optional($weight = 0.5, $default = null)
+ * @method Generator unique($reset = false, $maxRetries = 10000)
+ *
+ * @method integer biasedNumberBetween($min = 0, $max = 100, $function = 'sqrt')
+ *
+ * @property string $macProcessor
+ * @property string $linuxProcessor
  * @property string $userAgent
  * @property string $chrome
  * @property string $firefox
  * @property string $safari
  * @property string $opera
  * @property string $internetExplorer
+ * @property string $windowsPlatformToken
+ * @property string $macPlatformToken
+ * @property string $linuxPlatformToken
  *
  * @property string $uuid
  *
  * @property string $mimeType
  * @property string $fileExtension
+ * @method string file($sourceDirectory = '/tmp', $targetDirectory = '/tmp', $fullPath = true)
+ *
+ * @method string imageUrl($width = 640, $height = 480, $category = null, $randomize = true)
+ * @method string image($dir = null, $width = 640, $height = 480, $category = null, $fullPath = true)
  *
- * @property string $hexcolor
+ * @property string $hexColor
  * @property string $safeHexColor
- * @property string $rgbcolor
- * @property string $rgbColorAsArray
+ * @property string $rgbColor
+ * @property array $rgbColorAsArray
  * @property string $rgbCssColor
  * @property string $safeColorName
  * @property string $colorName

src/Faker/Provider/Base.php

@@ -193,7 +193,7 @@ public static function randomElement($array = array('a', 'b', 'c'))
      * Returns a random key from a passed associative array
      *
      * @param  array $array
-     * @return mixed
+     * @return int|string|null
      */
     public static function randomKey($array = array())
     {
@@ -238,8 +238,8 @@ public static function shuffle($arg = '')
      * Fisher–Yates algorithm, which is unbiaised, together with a Mersenne
      * twister random generator. This function is therefore more random than
      * PHP's shuffle() function, and it is seedable.
-     * 
-     * @link http://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle 
+     *
+     * @link http://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle
      *
      * @example $faker->shuffleArray([1, 2, 3]); // [2, 1, 3]
      *
@@ -276,8 +276,8 @@ public static function shuffleArray($array = array())
      * twister random generator. This function is therefore more random than
      * PHP's shuffle() function, and it is seedable. Additionally, it is
      * UTF8 safe if the mb extension is available.
-     * 
-     * @link http://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle 
+     *
+     * @link http://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle
      *
      * @example $faker->shuffleString('hello, world'); // 'rlo,h eold!lw'
      *
@@ -472,7 +472,7 @@ public static function toUpper($string = '')
      *
      * @param float $weight Set the probability of receiving a null value.
      *                            "0" will always return null, "1" will always return the generator.
-     * @return mixed|null
+     * @return Generator|DefaultGenerator
      */
     public function optional($weight = 0.5, $default = null)
     {
@@ -494,7 +494,7 @@ public function optional($weight = 0.5, $default = null)
      * @param boolean $reset      If set to true, resets the list of existing values
      * @param integer $maxRetries Maximum number of retries to find a unique value,
      *                                       After which an OverflowException is thrown.
-     * @throws OverflowException When no unique value can be found by iterating $maxRetries times
+     * @throws \OverflowException When no unique value can be found by iterating $maxRetries times
      *
      * @return UniqueGenerator A proxy class returning only non-existing values
      */

src/Faker/Provider/DateTime.php

@@ -23,6 +23,7 @@ protected static function getMaxTimestamp($max = 'now')
      * Get a timestamp between January 1, 1970 and now
      *
      * @param \DateTime|int|string $max maximum timestamp used as random end limit, default to "now"
+     * @return int
      *
      * @example 1061306726
      */
@@ -59,6 +60,7 @@ public static function dateTimeAD($max = 'now')
      * get a date string formatted with ISO8601
      *
      * @param \DateTime|int|string $max maximum timestamp used as random end limit, default to "now"
+     * @return string
      * @example '2003-10-21T16:05:52+0000'
      */
     public static function iso8601($max = 'now')
@@ -71,6 +73,7 @@ public static function iso8601($max = 'now')
      *
      * @param string               $format
      * @param \DateTime|int|string $max    maximum timestamp used as random end limit, default to "now"
+     * @return string
      * @example '2008-11-27'
      */
     public static function date($format = 'Y-m-d', $max = 'now')
@@ -83,6 +86,7 @@ public static function date($format = 'Y-m-d', $max = 'now')
      *
      * @param string               $format
      * @param \DateTime|int|string $max    maximum timestamp used as random end limit, default to "now"
+     * @return string
      * @example '15:02:34'
      */
     public static function time($format = 'H:i:s', $max = 'now')
@@ -158,6 +162,7 @@ public static function dateTimeThisMonth($max = 'now')
 
     /**
      * @param \DateTime|int|string $max maximum timestamp used as random end limit, default to "now"
+     * @return string
      * @example 'am'
      */
     public static function amPm($max = 'now')
@@ -167,6 +172,7 @@ public static function amPm($max = 'now')
 
     /**
      * @param \DateTime|int|string $max maximum timestamp used as random end limit, default to "now"
+     * @return string
      * @example '22'
      */
     public static function dayOfMonth($max = 'now')
@@ -176,6 +182,7 @@ public static function dayOfMonth($max = 'now')
 
     /**
      * @param \DateTime|int|string $max maximum timestamp used as random end limit, default to "now"
+     * @return string
      * @example 'Tuesday'
      */
     public static function dayOfWeek($max = 'now')
@@ -185,6 +192,7 @@ public static function dayOfWeek($max = 'now')
 
     /**
      * @param \DateTime|int|string $max maximum timestamp used as random end limit, default to "now"
+     * @return string
      * @example '7'
      */
     public static function month($max = 'now')
@@ -194,6 +202,7 @@ public static function month($max = 'now')
 
     /**
      * @param \DateTime|int|string $max maximum timestamp used as random end limit, default to "now"
+     * @return string
      * @example 'September'
      */
     public static function monthName($max = 'now')
@@ -203,6 +212,7 @@ public static function monthName($max = 'now')
 
     /**
      * @param \DateTime|int|string $max maximum timestamp used as random end limit, default to "now"
+     * @return int
      * @example 1673
      */
     public static function year($max = 'now')
@@ -211,6 +221,7 @@ public static function year($max = 'now')
     }
 
     /**
+     * @return string
      * @example 'XVII'
      */
     public static function century()
@@ -219,6 +230,7 @@ public static function century()
     }
 
     /**
+     * @return string
      * @example 'Europe/Paris'
      */
     public static function timezone()

src/Faker/Provider/File.php

@@ -566,7 +566,7 @@ public static function fileExtension()
      *
      * @param  string  $sourceDirectory The directory to look for random file taking
      * @param  string  $targetDirectory
-     * @param  boolean $fullPath        Wether to have the full path or just the filename
+     * @param  boolean $fullPath        Whether to have the full path or just the filename
      * @return string
      */
     public static function file($sourceDirectory = '/tmp', $targetDirectory = '/tmp', $fullPath = true)

src/Faker/Provider/Lorem.php

@@ -46,6 +46,7 @@ class Lorem extends \Faker\Provider\Base
 
     /**
      * @example 'Lorem'
+     * @return string
      */
     public static function word()
     {
@@ -73,7 +74,7 @@ public static function words($nb = 3, $asText = false)
     /**
      * Generate a random sentence
      *
-      * @example 'Lorem ipsum dolor sit amet.'
+     * @example 'Lorem ipsum dolor sit amet.'
      * @param integer $nbWords         around how many words the sentence should contain
      * @param boolean $variableNbWords set to false if you want exactly $nbWords returned,
      *                                  otherwise $nbWords may vary by +/-40% with a minimum of 1

src/Faker/Provider/Miscellaneous.php

@@ -181,6 +181,7 @@ class Miscellaneous extends \Faker\Provider\Base
      * Return a boolean, true or false
      *
      * @param integer $chanceOfGettingTrue Between 0 (always get false) and 100 (always get true).
+     * @return bool
      * @example true
      */
     public static function boolean($chanceOfGettingTrue = 50)

src/Faker/Provider/Payment.php

@@ -135,6 +135,7 @@ public static function creditCardType()
      * @param string  $type      Supporting any of 'Visa', 'MasterCard', 'Amercian Express', and 'Discover'
      * @param boolean $formatted Set to true if the output string should contain one separator every 4 digits
      * @param string  $separator Separator string for formatting card number. Defaults to dash (-).
+     * @return string
      *
      * @example '4485480221084675'
      */
@@ -161,6 +162,7 @@ public static function creditCardNumber($type = null, $formatted = false, $separ
 
     /**
      * @param boolean $valid True (by default) to get a valid expiration date, false to get a maybe valid date
+     * @return \DateTime
      * @example 04/13
      */
     public function creditCardExpirationDate($valid = true)
@@ -175,6 +177,7 @@ public function creditCardExpirationDate($valid = true)
     /**
      * @param boolean $valid                True (by default) to get a valid expiration date, false to get a maybe valid date
      * @param string  $expirationDateFormat
+     * @return string
      * @example '04/13'
      */
     public function creditCardExpirationDateString($valid = true, $expirationDateFormat = null)
@@ -184,7 +187,7 @@ public function creditCardExpirationDateString($valid = true, $expirationDateFor
 
     /**
      * @param  boolean $valid True (by default) to get a valid expiration date, false to get a maybe valid date
-     * @return array()
+     * @return array
      */
     public function creditCardDetails($valid = true)
     {