#6: Update the README file.

README.md

@@ -1,15 +1,88 @@
 ## PHPermutations
 [![Build Status](https://travis-ci.org/drupol/phpermutations.svg?branch=master)](https://travis-ci.org/drupol/phpermutations) [![Code Coverage](https://scrutinizer-ci.com/g/drupol/phpermutations/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/drupol/phpermutations/?branch=master) [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/drupol/phpermutations/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/drupol/phpermutations/?branch=master) [![Dependency Status](https://www.versioneye.com/user/projects/5870ade140543803e80abb5b/badge.svg?style=flat-square)](https://www.versioneye.com/user/projects/5870ade140543803e80abb5b)
 
-PHP iterators and generators to generate combinations and permutations in an efficient way.
+PHP Iterators and Generators to generate combinations and permutations in an efficient way.
 
 At first the library was created to only generate permutations and combinations.
+
 In the end, I added other Iterators and Generators like:
 * Fibonacci numbers,
 * Perfect numbers,
 * Prime numbers,
 * Product of numbers,
-* ... more to come.
+* Rotation of an array,
+* Cycling through an array,
+* Permutations,
+* Combinations,
+
+## Introduction
+
+I've always been fascinated by numbers and everything around them... in other words, mathematics.
+
+The library has been written first for being used in [PHPartition](https://github.com/drupol/phpartition), then it has
+been extended here and there.
+
+Its main use is for generating Permutations and Combinations without running out of memory, thanks to
+[PHP Generators](https://secure.php.net/manual/en/language.generators.overview.php) and 
+and [Iterators](https://secure.php.net/manual/en/class.iterator.php).
+
+The difference with other combinatorics library is that you can use an extra parameter 'length', that allows you to
+compute Permutations and Combinations of a particular size.
+The other notable difference is that your input arrays may contains any type of object (integers, arrays, strings or
+objects), the library will still continue to work without any trouble.
+
+## Requirements
+
+* PHP >= 5.6,
+* (optional) [PHPUnit](https://phpunit.de/) to run tests.
+
+## How to use
+
+Include this library in your project by doing:
+
+`composer require drupol/phpermutations`
+
+Let's say you want to find all the permutations of the list of number [1, 2, 3, 4, 5] having a length of 3:
+
+```php
+// Create the object
+$permutations = new \drupol\phpermutations\Generators\Permutations([1,2,3,4,5], 3);
+
+// Use a foreach loop.
+foreach ($permutations->generator() as $permutation) {// do stuff}
+
+// Or get the whole array at once.
+$permutations->toArray();
+```
+
+Most of the components always has the same arguments except for very few of them.
+
+As the documentation per component is not written yet, I advise you to
+[check the tests](https://github.com/drupol/phpermutations/tree/master/tests/src) to see how to use them.
+
+## Combinations
+
+> In mathematics, a combination is a way of selecting items from a collection, such that (unlike permutations) the order
+> of selection does not matter.
+>  -- [_Wikipedia_](https://en.wikipedia.org/wiki/Combination)
+
+In one sentence: _When the order doesn't matter, it is a Combination._
+
+## Examples
+
+Let's say we have a group of fruits:
+
+`$list = ['Apple', 'Pear', 'Banana', 'Orange']`
+
+and we want to find the combinations of length: `3`, the result will be:
+
+`['Apple', 'Pear', 'Banana']`
+
+`['Apple', 'Pear', 'Orange']`
+
+`['Apple', 'Banana', 'Orange']`
+
+`['Pear', 'Banana', 'Orange']`
 
 ## Permutations
 
@@ -76,35 +149,16 @@ and we want to find the permutations of length: `3`, the result will be:
 
 `['Orange', 'Banana', 'Pear']`
 
-## Combinations
-
-> In mathematics, a combination is a way of selecting items from a collection, such that (unlike permutations) the order
-> of selection does not matter.
->  -- [_Wikipedia_](https://en.wikipedia.org/wiki/Combination)
-
-In one sentence: _When the order doesn't matter, it is a Combination._
-
-## Examples
-
-Let's say we have a group of fruits
+The permutations of length 3 of the array [1, 2, 3, 4, 5] are, _please hold on tight_, the sum of all the permutations
+of each combinations having a length of 3 of that array.
 
-`$list = ['Apple', 'Pear', 'Banana', 'Orange']`
+## Tests
 
-and we want to find the combinations of length: `3`, the result will be:
+Each Generators and Iterators are tested using the same values as input. I try to be as much complete as possible with
+the [tests](https://github.com/drupol/phpermutations/tree/master/tests/fixtures).
+Every time the sources are modified, [Travis](https://travis-ci.org/drupol/phpermutations), the continuous integration
+service, tests the code against those tests, this way you are aware if the changes that you are introducing are valid.
 
-`['Apple', 'Pear', 'Banana']`
-
-`['Apple', 'Pear', 'Orange']`
-
-`['Apple', 'Banana', 'Orange']`
+# Contributing
 
-`['Pear', 'Banana', 'Orange']`
-
-## Inspired by
-
-* Many stackoverflow posts.
-
-## Requirements
-
-* PHP >= 5.6,
-* (optional) [PHPUnit](https://phpunit.de/) to run tests.
+Feel free to contribute to this library by sending Github pull requests. I'm quite reactive :-)