Adding pt_BR RG and improving docs

- Brazilian RG generator was included, as originally request by
  @hussani and @ianrodrigues at fzaninotto#488 and fzaninotto#551
- Check digit PHPDoc was included, moving in validation links from
  CPF and CNPJ generators

readme.md

@@ -898,6 +898,7 @@ echo $faker->name; // 'Sr. Luis Adriano Sepúlveda Filho'
 // Valid document generators have a boolean argument to remove formatting
 echo $faker->cpf;        // '145.343.345-76'
 echo $faker->cpf(false); // '45623467866'
+echo $faker->rg;         // '84.405.736-3'
 echo $faker->cnpj;       // '23.663.478/0001-24'
 ```
 

src/Faker/Provider/pt_BR/Company.php

@@ -19,7 +19,6 @@ class Company extends \Faker\Provider\Company
     /**
      * A random CNPJ number.
      * @link http://en.wikipedia.org/wiki/CNPJ
-     * @link http://pt.wikipedia.org/wiki/CNPJ#Algoritmo_de_Valida.C3.A7.C3.A3o
      * @param bool $formatted If the number should have dots/slashes/dashes or not.
      * @return string
      */

src/Faker/Provider/pt_BR/Person.php

@@ -102,10 +102,9 @@ public static function suffix()
         return static::randomElement(static::$suffix);
     }
 
-
     /**
      * A random CPF number.
-     * @link http://en.wikipedia.org/wiki/Cadastro_de_Pessoas_F%C3%ADsicas#Validation
+     * @link http://en.wikipedia.org/wiki/Cadastro_de_Pessoas_F%C3%ADsicas
      * @param bool $formatted If the number should have dots/dashes or not.
      * @return string
      */
@@ -117,4 +116,18 @@ public function cpf($formatted = true)
 
         return $formatted? vsprintf('%d%d%d.%d%d%d.%d%d%d-%d%d', str_split($n)) : $n;
     }
+
+    /**
+     * A random RG number, following Sao Paulo state's rules.
+     * @link http://pt.wikipedia.org/wiki/C%C3%A9dula_de_identidade
+     * @param bool $formatted If the number should have dots/dashes or not.
+     * @return string
+     */
+    public function rg($formatted = true)
+    {
+        $n = $this->generator->numerify('########');
+        $n .= check_digit($n);
+
+        return $formatted? vsprintf('%d%d.%d%d%d.%d%d%d-%s', str_split($n)) : $n;   
+    }
 }

src/Faker/Provider/pt_BR/check_digit.php

@@ -2,6 +2,15 @@
 
 namespace Faker\Provider\pt_BR;
 
+/**
+ * Calculates one MOD 11 check digit based on customary Brazilian algorithms.
+ * @link http://en.wikipedia.org/wiki/Check_digit
+ * @link http://pt.wikipedia.org/wiki/CNPJ#Algoritmo_de_Valida.C3.A7.C3.A3o
+ * @link http://en.wikipedia.org/wiki/Cadastro_de_Pessoas_F%C3%ADsicas#Validation
+ *
+ * @param string|integer $numbers Numbers on which generate the check digit
+ * @return integer
+ */
 function check_digit($numbers) {
     $length = strlen($numbers);
     $second_algorithm = $length >= 12;

test/Faker/Provider/pt_BR/PersonTest.php

@@ -22,4 +22,14 @@ public function testCpfFormatIsValid()
         $cpf = $this->faker->cpf(true);
         $this->assertRegExp('/\d{3}\.\d{3}\.\d{3}-\d{2}/', $cpf);
     }
+
+    public function testRgFormatIsValid()
+    {
+        $rg = $this->faker->rg(false);
+        echo $rg."\n";
+        $this->assertRegExp('/\d{8}\d/', $rg);
+        $rg = $this->faker->rg(true);
+        echo $rg."\n";
+        $this->assertRegExp('/\d{2}\.\d{3}\.\d{3}-[0-9X]/', $rg);
+    }
 }