add a documentor class to introspect generator capabilities

src/Documentor.php

@@ -0,0 +1,40 @@
+<?php
+
+namespace Faker;
+
+class Documentor
+{
+	protected $generator;
+	
+	public function __construct($generator)
+	{
+		$this->generator = $generator;
+	}
+	
+	public function getFormatters()
+	{
+		$formatters = array();
+		foreach ($this->generator->getProviders() as $provider) {
+			$providerClass = get_class($provider);
+			$formatters[$providerClass] = array();
+			$refl = new \ReflectionObject($provider);
+			foreach ($refl->getMethods(\ReflectionMethod::IS_PUBLIC) as $reflmethod) {
+				if ($reflmethod->name == '__construct') {
+					continue;
+				}
+				$comment = $reflmethod->getDocComment();
+				if (preg_match('/^\s+\*\s+@example\s+(.*)$/mi', $comment, $matches)) {
+					$example = $matches[1];
+				} else {
+					$example = '';
+				}
+				$formatters[$providerClass][$reflmethod->name] = $example;
+			}
+			ksort($formatters[$providerClass]);
+		}
+		ksort($formatters);
+		
+		return $formatters;
+	}
+	
+}

src/Generator.php

@@ -12,6 +12,11 @@ class Generator
 		$this->providers[]= $providers;
 	}
 	
+	public function getProviders()
+	{
+		return $this->providers;
+	}
+	
 	public function format($formatter, $arguments = array())
 	{
 		return call_user_func_array($this->getFormatter($formatter), $arguments);

src/Provider/Address.php

@@ -7,6 +7,7 @@ require_once __DIR__ . '/Base.php';
 class Address extends \Faker\Provider\Base
 {
 	protected static $citySuffix = array('Ville');
+	protected static $streetSuffix = array('Street');
 	protected static $cityFormats = array(
 		'{{firstName}}{{citySuffix}}',
 	);
@@ -21,54 +22,80 @@ class Address extends \Faker\Provider\Base
 	);
 
 	protected static $buildingNumber = array('##');
-	protected static $streetSuffix = array('Street');
 	protected static $postcode = array('#####');
 	protected static $country = array();
 	
+	/**
+	 * @example 'town'
+	 */
 	public static function citySuffix()
 	{
 		return static::randomElement(static::$citySuffix);
 	}
 
+	/**
+	 * @example 'Avenue'
+	 */
 	public static function streetSuffix()
 	{
 		return static::randomElement(static::$streetSuffix);
 	}
 
+	/**
+	 * @example '791'
+	 */
 	public static function buildingNumber()
 	{
 		return static::numerify(static::randomElement(static::$buildingNumber));
 	}
 
+	/**
+	 * @example 'Sashabury'
+	 */
 	public function city()
 	{
 		$format = static::randomElement(static::$cityFormats);
 		return $this->generator->parse($format);
 	}
-	
+
+	/**
+	 * @example 'Crist Parks'
+	 */
 	public function streetName()
 	{
 		$format = static::randomElement(static::$streetNameFormats);
 		return $this->generator->parse($format);
 	}
-	
+
+	/**
+	 * @example '791 Crist Parks'
+	 */
 	public function streetAddress()
 	{
 		$format = static::randomElement(static::$streetAddressFormats);
 		return $this->generator->parse($format);
 	}
 	
+	/**
+	 * @example 86039-9874
+	 */
 	public static function postcode()
 	{
 		return static::numerify(static::randomElement(static::$postcode));
 	}
 
+	/**
+	 * @example '791 Crist Parks, Sashabury, IL 86039-9874'
+	 */
 	public function address()
 	{
 		$format = static::randomElement(static::$addressFormats);
 		return $this->generator->parse($format);
 	}
 
+	/**
+	 * @example 'Japan'
+	 */
 	public static function country()
 	{
 		return static::randomElement(static::$country);

src/Provider/Company.php

@@ -12,12 +12,18 @@ class Company extends \Faker\Provider\Base
 
 	protected static $companySuffix = array('Ltd');
 
+	/**
+	 * @example 'Acme Ltd'
+	 */
 	public function company()
 	{
 		$format = static::randomElement(static::$formats);
 		return $this->generator->parse($format);
 	}
-	
+
+	/**
+	 * @example 'Ltd'
+	 */
 	public static function companySuffix()
 	{
 		return static::randomElement(static::$companySuffix);

src/Provider/Lorem.php

@@ -10,6 +10,9 @@ class Lorem extends \Faker\Provider\Base
 		'alias', 'consequatur', 'aut', 'perferendis', 'sit', 'voluptatem', 'accusantium', 'doloremque', 'aperiam', 'eaque', 'ipsa', 'quae', 'ab', 'illo', 'inventore', 'veritatis', 'et', 'quasi', 'architecto', 'beatae', 'vitae', 'dicta', 'sunt', 'explicabo', 'aspernatur', 'aut', 'odit', 'aut', 'fugit', 'sed', 'quia', 'consequuntur', 'magni', 'dolores', 'eos', 'qui', 'ratione', 'voluptatem', 'sequi', 'nesciunt', 'neque', 'dolorem', 'ipsum', 'quia', 'dolor', 'sit', 'amet', 'consectetur', 'adipisci', 'velit', 'sed', 'quia', 'non', 'numquam', 'eius', 'modi', 'tempora', 'incidunt', 'ut', 'labore', 'et', 'dolore', 'magnam', 'aliquam', 'quaerat', 'voluptatem', 'ut', 'enim', 'ad', 'minima', 'veniam', 'quis', 'nostrum', 'exercitationem', 'ullam', 'corporis', 'nemo', 'enim', 'ipsam', 'voluptatem', 'quia', 'voluptas', 'sit', 'suscipit', 'laboriosam', 'nisi', 'ut', 'aliquid', 'ex', 'ea', 'commodi', 'consequatur', 'quis', 'autem', 'vel', 'eum', 'iure', 'reprehenderit', 'qui', 'in', 'ea', 'voluptate', 'velit', 'esse', 'quam', 'nihil', 'molestiae', 'et', 'iusto', 'odio', 'dignissimos', 'ducimus', 'qui', 'blanditiis', 'praesentium', 'laudantium', 'totam', 'rem', 'voluptatum', 'deleniti', 'atque', 'corrupti', 'quos', 'dolores', 'et', 'quas', 'molestias', 'excepturi', 'sint', 'occaecati', 'cupiditate', 'non', 'provident', 'sed', 'ut', 'perspiciatis', 'unde', 'omnis', 'iste', 'natus', 'error', 'similique', 'sunt', 'in', 'culpa', 'qui', 'officia', 'deserunt', 'mollitia', 'animi', 'id', 'est', 'laborum', 'et', 'dolorum', 'fuga', 'et', 'harum', 'quidem', 'rerum', 'facilis', 'est', 'et', 'expedita', 'distinctio', 'nam', 'libero', 'tempore', 'cum', 'soluta', 'nobis', 'est', 'eligendi', 'optio', 'cumque', 'nihil', 'impedit', 'quo', 'porro', 'quisquam', 'est', 'qui', 'minus', 'id', 'quod', 'maxime', 'placeat', 'facere', 'possimus', 'omnis', 'voluptas', 'assumenda', 'est', 'omnis', 'dolor', 'repellendus', 'temporibus', 'autem', 'quibusdam', 'et', 'aut', 'consequatur', 'vel', 'illum', 'qui', 'dolorem', 'eum', 'fugiat', 'quo', 'voluptas', 'nulla', 'pariatur', 'at', 'vero', 'eos', 'et', 'accusamus', 'officiis', 'debitis', 'aut', 'rerum', 'necessitatibus', 'saepe', 'eveniet', 'ut', 'et', 'voluptates', 'repudiandae', 'sint', 'et', 'molestiae', 'non', 'recusandae', 'itaque', 'earum', 'rerum', 'hic', 'tenetur', 'a', 'sapiente', 'delectus', 'ut', 'aut', 'reiciendis', 'voluptatibus', 'maiores', 'doloribus', 'asperiores', 'repellat'
 	);
 
+	/**
+	 * @example 'Lorem'
+	 */
 	public static function word()
 	{
 		return static::randomElement(static::$wordList);
@@ -18,6 +21,7 @@ class Lorem extends \Faker\Provider\Base
 	/**
 	 * Generate an array of random words
 	 *
+	 * @example array('Lorem', 'ipsum', 'dolor')
 	 * @param integer $nb how many words to return
 	 * @return array
 	 */
@@ -33,6 +37,7 @@ class Lorem extends \Faker\Provider\Base
 	/**
 	 * Generate a random sentence
 	 *
+ 	 * @example 'Lorem ipsum dolor sit amet.'
 	 * @param integer $nbWords around how many words the sentence should contain
 	 * @return string
 	 */
@@ -47,6 +52,7 @@ class Lorem extends \Faker\Provider\Base
 	/**
 	 * Generate an array of sentences
 	 *
+	 * @example array('Lorem ipsum dolor sit amet.', 'Consectetur adipisicing eli.')
 	 * @param integer $nb how many sentences to return
 	 * @return array
 	 */
@@ -62,6 +68,7 @@ class Lorem extends \Faker\Provider\Base
 	/**
 	 * Generate a single paragraph
 	 *
+ 	 * @example 'Sapiente sunt omnis. Ut pariatur ad autem ducimus et. Voluptas rem voluptas sint modi dolorem amet.'
 	 * @param integer $nbSentences around how many sentences the paragraph should contain
 	 * @return string
 	 */
@@ -73,6 +80,7 @@ class Lorem extends \Faker\Provider\Base
 	/**
 	 * Generate an array of paragraphs
 	 *
+	 * @example array($paragraph1, $paragraph2, $paragraph3)
 	 * @param integer $nb how many paragraphs to return
 	 * @return array
 	 */
@@ -88,6 +96,7 @@ class Lorem extends \Faker\Provider\Base
 	/**
 	 * Generate a long text string
 	 *
+ 	 * @example 'Sapiente sunt omnis. Ut pariatur ad autem ducimus et. Voluptas rem voluptas sint modi dolorem amet.'
 	 * @param integer $nbParagraphs around how many paragraphs the text should contain
 	 * @return string
 	 */

src/Provider/Name.php

@@ -13,18 +13,27 @@ class Name extends \Faker\Provider\Base
 	protected static $firstName = array('John', 'Jane');
 	
 	protected static $lastName = array('Doe');
-		
+
+	/**
+	 * @example 'John Doe'
+	 */
 	public function name()
 	{
 		$format = static::randomElement(static::$formats);
 		return $this->generator->parse($format);
 	}
-	
+
+	/**
+	 * @example 'John'
+	 */
 	public static function firstName()
 	{
 		return static::randomElement(static::$firstName);
 	}
-	
+
+	/**
+	 * @example 'Doe'
+	 */
 	public static function lastName()
 	{
 		return static::randomElement(static::$lastName);

src/Provider/PhoneNumber.php

@@ -7,7 +7,10 @@ require_once __DIR__ . '/Base.php';
 class PhoneNumber extends \Faker\Provider\Base
 {
 	protected static $formats = array('###-###-###');
-	
+
+	/**
+	 * @example '555-123-546'
+	 */
 	public static function phoneNumber()
 	{
 		return static::numerify(static::randomElement(static::$formats));

src/Provider/en_US/Address.php

@@ -64,22 +64,34 @@ class Address extends \Faker\Provider\Address
 		"{{streetAddress}}\n{{city}}, {{stateAbbr}} {{postcode}}",
 	);
 	protected static $secondaryAddressFormats = array('Apt. ###', 'Suite ###');
-	
+
+	/**
+	 * @example 'East'
+	 */
 	public static function cityPrefix()
 	{
 		return static::randomElement(static::$cityPrefix);
 	}
-	
+
+	/**
+	 * @example 'Appt. 350'
+	 */
 	public static function secondaryAddress()
 	{
 		return static::numerify(static::randomElement(static::$secondaryAddressFormats));
 	}
 
+	/**
+	 * @example 'California'
+	 */
 	public static function state()
 	{
 		return static::randomElement(static::$state);
 	}
-	
+
+	/**
+	 * @example 'CA'
+	 */	
 	public static function stateAbbr()
 	{
 		return static::randomElement(static::$stateAbbr);

src/Provider/en_US/Company.php

@@ -38,6 +38,9 @@ class Company extends \Faker\Provider\Company
 
 	protected static $companySuffix = array('Inc','and Sons','LLC','Group','PLC','Ltd');
 
+	/**
+	 * @example 'Robust full-range hub'
+	 */
 	public function catchPhrase()
 	{
 		$result = array();
@@ -47,7 +50,10 @@ class Company extends \Faker\Provider\Company
 		
 		return join($result, ' ');
 	}
-	
+
+	/**
+	 * @example 'integrate extensible convergence'
+	 */
 	public function bs()
 	{
 		$result = array();

src/Provider/en_US/Name.php

@@ -76,12 +76,18 @@ class Name extends \Faker\Provider\Name
 	private static $prefix = array('Mr.','Mrs.','Ms.','Miss','Dr.');
 	
 	private static $suffix = array('Jr.','Sr.','I','II','III','IV','V','MD','DDS','PhD','DVM');
-	
+
+	/**
+	 * @example 'Mrs.'
+	 */
 	public static function prefix()
 	{
 		return static::randomElement(static::$prefix);
 	}
-	
+
+	/**
+	 * @example 'PhD'
+	 */
 	public static function suffix()
 	{
 		return static::randomElement(static::$suffix);

test/documentor.php

@@ -0,0 +1,7 @@
+<?php
+require_once __DIR__ . '/../src/Factory.php';
+require_once __DIR__ . '/../src/Documentor.php';
+
+$generator = Faker\Factory::create();
+$documentor = new Faker\Documentor($generator);
+print_r($documentor->getFormatters());

test/test.php

@@ -33,4 +33,4 @@ $generator = Faker\Factory::create();
 <?php endif; ?>
   </contact>
 <?php endfor; ?>
-</contacts>
+</contacts>