docs: Update documentation.

Signed-off-by: Pol Dellaiera <pol.dellaiera@protonmail.com>

README.md

@@ -37,7 +37,7 @@ On top of this, this library:
  * uses [S.O.L.I.D. principles][solid on wikipedia],
  * does not have any external dependency,
  * fully tested,
- * type safe (_type safe @ > 94%_),
+ * type safe (_type safe @ > 95%_),
  * framework agnostic.
 
 Except a few methods, most methods are [pure][pure function on wikipedia] and return a

docs/index.rst

@@ -1,5 +1,5 @@
-Collection
-==========
+PHP Collection
+==============
 
 Collection is a functional utility library for PHP greater than 7.1.3.
 
@@ -25,7 +25,7 @@ On top of this, this library:
  * uses `S.O.L.I.D. principles`_,
  * does not have any external dependency,
  * fully tested,
- * type safe (*type safe @ > 98%*),
+ * type safe (*type safe @ > 95%*),
  * framework agnostic.
 
 Except a few methods, most methods are `pure`_ and return a `new Collection object`_.
@@ -45,9 +45,100 @@ This library has been inspired by:
  * `mtdowling/transducers`_
  * `Ruby Array`_
  * `Collect.js`_
+ * `Rambda`_
  * `nikic/iter`_
+ * `Haskell`_
  * `Lazy.js`_
 
+Features
+--------
+
+-  **Decoupled**: Each Collection methods is a shortcut to one isolated
+   standard class, each operation has its own responsibility. Usually
+   the arguments needed are standard PHP variables like ``int``,
+   ``string``, ``callable`` or ``iterator``. It allows users to use
+   those operations individually, at their own will to build up
+   something custom. Currently, more than :ref:`80 operations <api>`
+   are available in this library. This library is basically an
+   example of what you can do with all those small bricks, but nothing
+   prevent users to use an operation on its own as well.
+
+-  **It takes function first, data-last**: In the following example,
+   multiple operations are created. The data to be operated on is
+   generally supplied at last.
+
+   .. code:: php
+
+      <?php
+
+      $data = ['foo', 'bar', 'baz'];
+      $filterCallback = static fn(string $userId): bool => 'foo' !== $userId;
+
+      // Using the Collection library
+      $collection = Collection::fromIterable($data)
+          ->filter($filterCallback)
+          ->reverse();
+      print_r($collection->all()); // ['baz', 'bar']
+
+      // Using single operations.
+      $filter = Filter::of()($filterCallback);
+      $reverse = Reverse::of();
+      $pipe = Pipe::of()($reverse, $filter);
+
+      print_r(iterator_to_array($pipe(new ArrayIterator($data))));  // ['baz', 'bar']
+
+   More information about this in the `Brian Lonsdorf's conference`_, 
+   even if this is for Javascript, 
+   those concepts are common to other programming languages.
+
+   In a nutshell, the combination of currying and function-first enables
+   the developer to compose functions with very little code (*often in a
+   “point-free” fashion*), before finally passing in the relevant user
+   data.
+
+-  **Operations are stateless and curried by default**: This currying
+   makes it easy to compose functions to create new functions. Because
+   the API is *function-first*, *data-last*, you can continue composing
+   and composing until you build up the function you need before
+   dropping in the data. See `this Hugh Jackson article`_ describing 
+   the advantages of this style.
+
+   In the following example, the well-known `flatMap`_ could
+   be composed of other operations as such:
+
+   .. code:: php
+
+      <?php
+
+      $input = ['foo,bar', 'baz,john'];
+      $userData = new ArrayIterator($input);
+
+      $flatMap = static fn (callable $callable) =>
+                     Pipe::of()(
+                        Map::of()($callable),
+                        Flatten::of()(1),
+                        Normalize::of()
+                     );
+
+      $callback = fn(string $name): array => explode(',', $name);
+
+      print_r(iterator_to_array($flatMap($callback)($userData))); // ['foo', 'bar', 'baz', 'john']
+
+
+On the internet
+---------------
+
+ * `Reddit announcement thread`_
+ * `Reddit release 2.0.0 thread`_
+ * `Featured in PHPStorm Annotated August 2020`_
+
+Changelog
+---------
+
+See `CHANGELOG.md`_ for a changelog based on `git commits`_.
+
+For more detailed changelogs, please check `the release changelogs`_.
+
 .. _array_map(): https://www.php.net/array-map
 .. _array_filter(): https://www.php.net/array-filter
 .. _array_reduce(): https://www.php.net/array-reduce
@@ -56,6 +147,8 @@ This library has been inspired by:
 .. _mtdowling/transducers: https://github.com/mtdowling/transducers.php
 .. _Ruby Array: https://ruby-doc.org/core-2.7.0/Array.html
 .. _Collect.js: https://collect.js.org
+.. _Rambda: https://ramdajs.com/
+.. _Haskell: https://www.haskell.org/
 .. _new Collection object: https://github.com/loophp/collection/blob/master/src/Collection.php
 .. _SplObjectStorage: https://www.php.net/manual/en/class.splobjectstorage.php
 .. _this example: https://loophp-collection.readthedocs.io/en/latest/pages/usage.html#manipulate-keys-and-values
@@ -71,6 +164,15 @@ This library has been inspired by:
 .. _PSR-4: https://www.php-fig.org/psr/psr-4/
 .. _PSR-12: https://www.php-fig.org/psr/psr-12/
 .. _Ruby arrays: https://apidock.com/ruby/Array
+.. _Brian Lonsdorf's conference: https://www.youtube.com/watch?v=m3svKOdZijA
+.. _this Hugh Jackson article: http://hughfdjackson.com/javascript/why-curry-helps/
+.. _flatMap: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/flatMap
+.. _Reddit announcement thread: https://www.reddit.com/r/PHP/comments/csxw23/a_stateless_and_modular_collection_class/
+.. _Reddit release 2.0.0 thread: https://www.reddit.com/r/PHP/comments/i2u2le/release_of_version_200_of_loophpcollection/
+.. _Featured in PHPStorm Annotated August 2020: https://blog.jetbrains.com/phpstorm/2020/08/php-annotated-august-2020/
+.. _CHANGELOG.md: https://github.com/loophp/collection/blob/master/CHANGELOG.md
+.. _git commits: https://github.com/loophp/collection/commits/master
+.. _the release changelogs: https://github.com/loophp/collection/releases
 
 .. toctree::
     :hidden:

docs/pages/api.rst

@@ -1,3 +1,5 @@
+.. _api:
+
 API
 ===