From ef74dae5d8210c7efc873e13d2d3ea58336fe184 Mon Sep 17 00:00:00 2001
From: Francois Zaninotto <fzaninotto@gmail.com>
Date: Sat, 15 Oct 2011 14:13:20 +0200
Subject: [PATCH] Document all formatters. Closes #3.

---
 readme.md           | 46 +++++++++++++++++++++++++++++++++++++++++++--
 test/documentor.php |  8 +++++++-
 2 files changed, 51 insertions(+), 3 deletions(-)

diff --git a/readme.md b/readme.md
index bdbe6ad1..bdf5d925 100644
--- a/readme.md
+++ b/readme.md
@@ -31,10 +31,49 @@ echo $faker->lorem;
   // Ea quaerat et quisquam. Deleniti sunt quam. Adipisci consequatur id in occaecati. 
   // Et sint et. Ut ducimus quod nemo ab voluptatum.
 ```
+## Formatters
 
+Here is a list of the bundled formatters in the default locale.
+
+### Lorem
+ * `lorem()`            // 'Sapiente sunt omnis. Ut pariatur ad autem ducimus et. Voluptas rem voluptas sint modi dolorem amet.'  
+ * `paragraph()`        // 'Sapiente sunt omnis. Ut pariatur ad autem ducimus et. Voluptas rem voluptas sint modi dolorem amet.'  
+ * `paragraphs()`       // array($paragraph1, $paragraph2, $paragraph3)  
+ * `sentence()`         // 'Lorem ipsum dolor sit amet.'  
+ * `sentences()`        // array('Lorem ipsum dolor sit amet.', 'Consectetur adipisicing eli.')  
+ * `word()`             // 'Lorem'  
+ * `words()`            // array('Lorem', 'ipsum', 'dolor')  
+### Address
+ * `address()`          // '791 Crist Parks, Sashabury, IL 86039-9874'  
+ * `buildingNumber()`   // '791'  
+ * `city()`             // 'Sashabury'  
+ * `cityPrefix()`       // 'East'  
+ * `citySuffix()`       // 'town'  
+ * `country()`          // 'Japan'  
+ * `postcode()`         // 86039-9874  
+ * `secondaryAddress()` // 'Appt. 350'  
+ * `state()`            // 'California'  
+ * `stateAbbr()`        // 'CA'  
+ * `streetAddress()`    // '791 Crist Parks'  
+ * `streetName()`       // 'Crist Parks'  
+ * `streetSuffix()`     // 'Avenue'  
+### Company
+ * `bs()`               // 'integrate extensible convergence'  
+ * `catchPhrase()`      // 'Robust full-range hub'  
+ * `company()`          // 'Acme Ltd'  
+ * `companySuffix()`    // 'Ltd'  
+### Name
+ * `firstName()`        // 'John'  
+ * `lastName()`         // 'Doe'  
+ * `name()`             // 'John Doe'  
+ * `prefix()`           // 'Mrs.'  
+ * `suffix()`           // 'PhD'  
+### PhoneNumber
+ * `phoneNumber()`      // '555-123-546'
+ 
 ## Providers
 
-As a matter of fact, a `Faker\Generator` alone can't do much generation. It needs `Faker\Provider` objects to delegate the data generation to them. `Faker\Factory` actually creates a `Faker\Generator` bundled with the default providers. Here is what happens under the hood:
+As a matter of fact, a `Faker\Generator` alone can't do much generation. It needs `Faker\Provider` objects to delegate the data generation to them. `Faker\Factory::create()` actually creates a `Faker\Generator` bundled with the default providers. Here is what happens under the hood:
 
 ```php
 <?php
@@ -50,10 +89,13 @@ Whenever you try to access a property on the `$faker` object, the generator look
 
 That means that you can esily add your own providers to a `Faker\Generator`. Just have a look at the existing providers to see how you can design powerful data generators in no time.
 
-`Faker\Factory` can take a locale as an argument, to return localized data. If no localized provider is found, the factory returns a provider with the default locale.
+## Localization
+
+`Faker\Factory` can take a locale as an argument, to return localized data. If no localized provider is found, the factory fallbacks to the default locale.
 
 ```php
 $faker = Faker\Factory::create('fr_FR'); // create a French faker
+echo $faker->name; // 'Jean Dupont'
 ```
 
 ## Real Life Usage
diff --git a/test/documentor.php b/test/documentor.php
index b338abfc..e2fd1480 100644
--- a/test/documentor.php
+++ b/test/documentor.php
@@ -4,4 +4,10 @@ require_once __DIR__ . '/../src/Documentor.php';
 
 $generator = Faker\Factory::create();
 $documentor = new Faker\Documentor($generator);
-print_r($documentor->getFormatters());
+?>
+<?php foreach ($documentor->getFormatters() as $provider => $formatters): ?>
+### `<?php echo $provider ?>`
+<?php foreach ($formatters as $formatter => $example): ?>
+ * <?php echo str_pad('`' . $formatter . '()`', 20) ?><?php if ($example): ?> // <?php echo $example ?> <?php endif; ?> 
+<?php endforeach; ?>
+<?php endforeach; ?>