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 @@ public function addProvider($providers)
 		$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 @@
 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 @@ public static function word()
 	/**
 	 * 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 @@ public static function words($nb = 3)
 	/**
 	 * 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 @@ public function sentence($nbWords = 3)
 	/**
 	 * 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 @@ public function sentences($nb = 3)
 	/**
 	 * 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 @@ public function paragraph($nbSentences = 3)
 	/**
 	 * Generate an array of paragraphs
 	 *
+	 * @example array($paragraph1, $paragraph2, $paragraph3)
 	 * @param integer $nb how many paragraphs to return
 	 * @return array
 	 */
@@ -88,6 +96,7 @@ public function paragraphs($nb)
 	/**
 	 * 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 @@
 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 @@ public function catchPhrase()
 
 		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 @@
 <?php endif; ?>
   </contact>
 <?php endfor; ?>
-</contacts>
+</contacts>