Update ReadMe.md

ReadMe.md

@@ -2,8 +2,8 @@
 
 # Helper for PhpUnit @dataProvider
 
-Handy `require-dev` testing tool for [PhpUnit](https://github.com/sebastianbergmann/phpunit).
-It allows to manage data providers with `zip()`, `join()`, `cross()`, `pairs()`, `slice()` and more.
+Handy `require-dev` testing tool for [PhpUnit]. It allows to manage data providers
+with `zip()`, `join()`, `cross()`, `pairs()`, `slice()` and more.
 
 [![Build Status](https://github.com/t-regx/CrossDataProviders/workflows/build/badge.svg?branch=master)][build]
 [![Coverage Status](https://coveralls.io/repos/github/t-regx/CrossDataProviders/badge.svg?branch=master)][coveralls]
@@ -25,19 +25,118 @@ It allows to manage data providers with `zip()`, `join()`, `cross()`, `pairs()`,
 [repository]: https://github.com/t-regx/CrossDataProviders
 [license]: https://github.com/t-regx/CrossDataProviders/blob/master/LICENSE
 [coveralls]: https://coveralls.io/github/t-regx/CrossDataProviders?branch=master
+[PhpUnit]: https://github.com/sebastianbergmann/phpunit
 
 [![PRs Welcome](https://img.shields.io/badge/PR-welcome-brightgreen.svg?style=popout)](https://github.com/t-regx/CrossDataProviders/pulls)
 
 1. [Installation](#installation)
     * [Composer](#installation)
-2. [Migration](#mi)
+2. [Overview](#overview)
+    * [Functionalities](#functionalities)
+    * [Features](#features)
+    * [Example](#example-usage)
+3. [Migration](#migration-from-previous-version)
 
 # Installation
 
 Installation for PHP 7.1 and later:
 
 ```bash
-$ composer require --dev rawr/phpunit-data-provider
+composer require --dev rawr/phpunit-data-provider
+```
+
+# Overview
+
+Class `DataProvider` can be used to build, compose and edit data providers to be used with [PhpUnit]
+by [@sebastianbergmann](https://github.com/sebastianbergmann).
+
+### Functionalities:
+
+Creating new data providers:
+
+- `DataProvider::list()`, `DataProvider::sets()`, `DataProvider::dictionary()`, `DataProvider::pairs()`, `DataProvider::distinctPairs()`
+
+Composing existing providers:
+
+- `DataProvider::zip()`, `DataProvider::join()`, `DataProvider::cross()`, `DataProvider::of()`
+
+Editing existing providers:
+
+- `DataProvider.slice()`, `DataProvider.drop()`
+
+### Features:
+
+- `DataProvider` accepts many types: `array`, `iterable`, [`\Traversable`], [`\Iterator`], [`\IteratorAggregate`], [`\Generator`] and also `DataProvider`.
+- each builder method (`list()`, `sets()`, etc.) set proper keys of data provider, based on values
+- properly handles duplicates in keys, formatting them in an informative manner
+
+[`\Traversable`]: https://www.php.net/manual/en/class.traversable.php
+
+[`\Iterator`]: https://www.php.net/manual/en/class.iterator.php
+
+[`\IteratorAggregate`]: https://www.php.net/manual/en/class.iteratoraggregate.php
+
+[`\Generator`]: https://www.php.net/manual/en/class.generator.php
+
+### Example usage
+
+`DataProvider::cross()` returns an instance of `DataProvider` which is a square matrix of input data providers.
+
+```php
+/**
+ * @test
+ * @dataProvider services
+ */
+public function shouldLogin(string $service, string $method, int $port): void {
+    // your test here
+}
+
+public function services(): DataProvider {
+    return DataProvider::cross(
+      [
+        ['github.com'], ['bitbucket.com'], ['gitlab.com'], ['sourceforge.net']
+      ],
+      [
+        ['http', 80],
+        ['https', 443],
+        ['ssh', 22]
+      ]
+    );
+}
+```
+
+This is equivalent of having a regular data provider that is composed of 12 entries, that look like this:
+
+```php
+public function services(): array {
+    return [
+        ['github.com', 'http', 80],
+        ['github.com', 'https', 443],
+        ['github.com', 'ssh', 22],
+        ['bitbucket.com', 'http', 80],
+        ['bitbucket.com', 'https', 443],
+        ['bitbucket.com', 'ssh', 22],
+        ['gitlab.com', 'http', 80],
+        ['gitlab.com', 'https', 443],
+        ['gitlab.com', 'ssh', 22],
+        ['sourceforge.net', 'http', 80],
+        ['sourceforge.net', 'https', 443],
+        ['sourceforge.net', 'ssh', 22],
+    ];
+}
+```
+
+`DataProvider::cross()` accepts data providers of different types: `array`, `\Iterator`, `\IteratorAggregate`, `\Traversable`, `\Generator`,
+`iterable` and `DataProvider`.
+
+That means `DataProvider` can be composed together.
+
+```php
+public function services(): DataProvider {
+    return DataProvider::cross(
+      DataProvider::list('github.com', 'bitbucket.com', 'gitlab.com', 'sourceforge.net'),
+      DataProvider::sets(['http', 80], ['https', 443], ['ssh', 22]));
+}
 ```
 
 # Migration from previous version