some readme updates; fix some docblocks;

Author: SlayerBirden

.gitignore

@@ -1,2 +1,2 @@
 /vendor
-composer.lock
+/composer.lock

README.md

@@ -8,8 +8,12 @@ Build a pipeline to pour your data through!
 ## About
 
 This is a low level lib that helps you with building a data migration process.
-It requires a little bootstrapping to float, but it can be easily done if you need just a minimal process
- or just looking to test things out.
+It requires a little bootstrapping to float, but it can be easily done if you just need a minimal process
+ or looking to test things out.
+
+The main idea is that you're building a pipeline where each section can mutate the data that's flowing through.
+It allows process to be extremely flexible, since each new step can potentially get (**completely**) transformed data.
+It also can be very dangerous, since mistake can be costly, hence we crafted awesome error handling and reporting mechanisms.
 
 ## Examples
 
@@ -99,14 +103,14 @@ $pipeline = (new PipelineBuilder($emitter))
 ![results](examples/example1-import-cli/2-cli-runs.png)
 
 ## Goals
-* Easy to maintain. Strong reporting shows what exactly is wrong with the data or the process.
-* Flexible. Extremely flexible workflow allows to work with different import/export/migration scenarios.
+* **Easy to maintain**. Strong reporting shows what exactly went wrong.
+* **Flexible**. Extremely flexible workflow allows to work with different import/export/migration scenarios.
     * one file -> multiple tables
     * multiple files -> one table
-    * supports dynamic connection
+    * supports dynamic DB connection
     * supports different source types and destination types
-* Fast. Low level operations produce maximum flow speed.
-* Stable. Strong test coverage guarantees bug-free groundwork.
+* **Fast**. Low level operations produce maximum flow speed.
+* **Stable**. Strong test coverage guarantees bug-free groundwork.
 
 ## Influences
 * [Ddeboer Data Import library](https://github.com/ddeboer/data-import)

src/Pipe/Copy.php

@@ -30,6 +30,12 @@ public function __construct(string $id, string $from, string $to)
         $this->to = $to;
     }
 
+    /**
+     * Copy data from one key to another. Create if doesn't exist.
+     *
+     * @param DataBagInterface $dataBag
+     * @return DataBagInterface
+     */
     public function pass(DataBagInterface $dataBag): DataBagInterface
     {
         $from = $dataBag[$this->from] ?? null;

src/Pipe/Delete.php

@@ -25,6 +25,12 @@ public function __construct(string $id, string ...$fieldNames)
         $this->fieldNames = $fieldNames;
     }
 
+    /**
+     * Delete data from the bag by key[s]
+     *
+     * @param DataBagInterface $dataBag
+     * @return DataBagInterface
+     */
     public function pass(DataBagInterface $dataBag): DataBagInterface
     {
         foreach ($this->fieldNames as $name) {

src/Pipe/Swap.php

@@ -30,6 +30,12 @@ public function __construct(string $id, string $first, string $second)
         $this->second = $second;
     }
 
+    /**
+     * Swap one key with another.
+     *
+     * @param DataBagInterface $dataBag
+     * @return DataBagInterface
+     */
     public function pass(DataBagInterface $dataBag): DataBagInterface
     {
         $first = $dataBag[$this->first] ?? null;