From b38f633534a8e5c388e1def181e75676b5aa7f24 Mon Sep 17 00:00:00 2001
From: Geoffrey Brier <geoffrey@widop.com>
Date: Tue, 5 Jun 2012 21:49:16 +0200
Subject: [PATCH] Added phpdoc concerning new formatters (fr_FR)

---
 src/Faker/Provider/fr_FR/Address.php | 30 ++++++++++++++++++++++++++++
 src/Faker/Provider/fr_FR/Company.php | 15 ++++++++++++++
 2 files changed, 45 insertions(+)

diff --git a/src/Faker/Provider/fr_FR/Address.php b/src/Faker/Provider/fr_FR/Address.php
index 5041565b..7f4740a5 100644
--- a/src/Faker/Provider/fr_FR/Address.php
+++ b/src/Faker/Provider/fr_FR/Address.php
@@ -83,25 +83,55 @@ class Address extends \Faker\Provider\Address
 		return static::randomElement(static::$streetPrefix);
 	}
 
+	/**
+	 * Randomly returns a french region.
+	 *
+	 * @example 'Guadeloupe'
+	 *
+	 * @return string
+	 */
 	public static function region()
 	{
 		return static::randomElement(static::$regions);
 	}
 
+	/**
+	 * Randomly returns a french department ('departmentNumber' => 'departmentName').
+	 *
+	 * @example array('2B' => 'Haute-Corse')
+	 *
+	 * @return array
+	 */
 	public static function department()
 	{
 		return static::randomElement(static::$departments);
 	}
 
+	/**
+	 * Randomly returns a french department name.
+	 *
+	 * @example 'Ardèche'
+	 *
+	 * @return string
+	 */
 	public static function departmentName()
 	{
 		$randomDepartmentName = array_values(static::department());
+
 		return $randomDepartmentName[0];
 	}
 
+	/**
+	 * Randomly returns a french department number.
+	 *
+	 * @example '59'
+	 *
+	 * @return string
+	 */
 	public static function departmentNumber()
 	{
 		$randomDepartmentNumber = array_keys(static::department());
+
 		return $randomDepartmentNumber[0];
 	}
 }
\ No newline at end of file
diff --git a/src/Faker/Provider/fr_FR/Company.php b/src/Faker/Provider/fr_FR/Company.php
index 4f4af297..a84450e0 100644
--- a/src/Faker/Provider/fr_FR/Company.php
+++ b/src/Faker/Provider/fr_FR/Company.php
@@ -15,6 +15,16 @@ class Company extends \Faker\Provider\Company
 
 	protected static $sirenFormat = "### ### ###";
 
+	/**
+	 * Generates a siret number (14 digits).
+	 * It is in fact the result of the concatenation of a siren number (9 digits),
+	 * a sequential number (4 digits) and a control number (1 digit) concatenation.
+	 * If $maxSequentialDigits is invalid, it is set to 2.
+	 *
+	 * @param int $maxSequentialDigits The maximum number of digits for the sequential number (> 0 && <= 4).
+	 *
+	 * @return string
+	 */
 	public static function siret($maxSequentialDigits = 2)
 	{
 		if ($maxSequentialDigits > 4 || $maxSequentialDigits <= 0) {
@@ -26,6 +36,11 @@ class Company extends \Faker\Provider\Company
 		return  static::numerify(static::siren() . ' ' . $sequentialNumber . '#');
 	}
 
+        /**
+         * Generates a siren number (9 digits).
+         *
+         * @return string
+         */
 	public static function siren()
 	{
 		return static::numerify(static::$sirenFormat);