Changed AnysyncTransformer to @internal.

Avoided exposing AynsyncTransformer on any public interface, using concrete Transformer types instead.
Added and rewrote some public method docblocks.

Author: Bilge

src/Connector/AsyncConnector.php

@@ -6,14 +6,14 @@
 use Amp\Promise;
 
 /**
- * Provides a method for fetching data from a source asynchronously.
+ * Provides a method for fetching data from a data source asynchronously.
  */
 interface AsyncConnector
 {
     /**
-     * Fetches data from the specified source.
+     * Fetches data asynchronously from the specified data source.
      *
-     * @param DataSource $source Source.
+     * @param DataSource $source Data source.
      *
      * @return Promise<mixed> Data.
      */

src/Connector/Connector.php

@@ -4,14 +4,14 @@
 namespace ScriptFUSION\Porter\Connector;
 
 /**
- * Provides a method for fetching data from a source.
+ * Provides a method for fetching data from a data source.
  */
 interface Connector
 {
     /**
-     * Fetches data from the specified source.
+     * Fetches data from the specified data source.
      *
-     * @param DataSource $source Source.
+     * @param DataSource $source Data source.
      *
      * @return mixed Data.
      */

src/Connector/ImportConnector.php

@@ -66,6 +66,13 @@ public function __construct(
         $this->maxFetchAttempts = $maxFetchAttempts;
     }
 
+    /**
+     * Fetches data from the specified data source.
+     *
+     * @param DataSource $source Data source.
+     *
+     * @return mixed Data.
+     */
     public function fetch(DataSource $source)
     {
         return retry(
@@ -77,6 +84,13 @@ function () use ($source) {
         );
     }
 
+    /**
+     * Fetches data asynchronously from the specified data source.
+     *
+     * @param DataSource $source Data source.
+     *
+     * @return Promise<mixed> Data.
+     */
     public function fetchAsync(DataSource $source): Promise
     {
         return retryAsync(
@@ -145,7 +159,7 @@ private static function invokeHandler(
     }
 
     /**
-     * Gets the wrapped connector. Useful for resources to reconfigure connector options during this import.
+     * Gets the wrapped connector.
      *
      * @return Connector|AsyncConnector Wrapped connector.
      */

src/Porter.php

@@ -28,7 +28,7 @@
 use function Amp\call;
 
 /**
- * Imports data from a provider defined in the providers container or internal factory.
+ * Imports data from a provider defined in the container of providers or the internal factory.
  */
 class Porter
 {
@@ -53,11 +53,12 @@ public function __construct(ContainerInterface $providers)
     }
 
     /**
-     * Imports data according to the design of the specified import specification.
+     * Imports a one or more records from the resource contained in the specified import specification.
      *
      * @param ImportSpecification $specification Import specification.
      *
-     * @return PorterRecords|CountablePorterRecords
+     * @return PorterRecords|CountablePorterRecords Collection of records. If the total size of the collection is known,
+     *     the collection may implement Countable, otherwise PorterRecords is returned.
      */
     public function import(ImportSpecification $specification): PorterRecords
     {
@@ -75,7 +76,7 @@ public function import(ImportSpecification $specification): PorterRecords
     }
 
     /**
-     * Imports one record according to the design of the specified import specification.
+     * Imports one record from the resource contained in the specified import specification.
      *
      * @param ImportSpecification $specification Import specification.
      *
@@ -122,11 +123,13 @@ private function fetch(ImportSpecification $specification): \Iterator
     }
 
     /**
-     * Imports data asynchronously according to the design of the specified asynchronous import specification.
+     * Imports one or more records asynchronously from the resource contained in the specified asynchronous import
+     * specification.
      *
      * @param AsyncImportSpecification $specification Asynchronous import specification.
      *
-     * @return AsyncPorterRecords|CountableAsyncPorterRecords
+     * @return AsyncPorterRecords|CountableAsyncPorterRecords Collection of records. If the total size of the
+     *     collection is known, the collection may implement Countable, otherwise AsyncPorterRecords is returned.
      */
     public function importAsync(AsyncImportSpecification $specification): AsyncRecordCollection
     {
@@ -148,11 +151,11 @@ public function importAsync(AsyncImportSpecification $specification): AsyncRecor
     }
 
     /**
-     * Imports one record according to the design of the specified asynchronous import specification.
+     * Imports one record from the resource contained in the specified asynchronous import specification.
      *
      * @param AsyncImportSpecification $specification Asynchronous import specification.
      *
-     * @return Promise Promise that resolves to a record.
+     * @return Promise<array|null> Record.
      */
     public function importOneAsync(AsyncImportSpecification $specification): Promise
     {
@@ -265,7 +268,7 @@ private function createAsyncPorterRecords(
      *
      * @param string $name Provider name.
      *
-     * @return Provider|AsyncProvider
+     * @return Provider|AsyncProvider Provider.
      *
      * @throws ProviderNotFoundException The specified provider was not found.
      */

src/Provider/AsyncProvider.php

@@ -11,7 +11,7 @@
 interface AsyncProvider
 {
     /**
-     * Gets a connector for accessing resource data.
+     * Gets an asynchronous connector compatible with this provider's resources.
      */
     public function getAsyncConnector(): AsyncConnector;
 }

src/Provider/Provider.php

@@ -11,7 +11,7 @@
 interface Provider
 {
     /**
-     * Gets a connector for accessing resource data.
+     * Gets a connector compatible with this provider's resources.
      */
     public function getConnector(): Connector;
 }

src/Provider/Resource/AsyncResource.php

@@ -6,6 +6,9 @@
 use Amp\Iterator;
 use ScriptFUSION\Porter\Connector\ImportConnector;
 
+/**
+ * Defines methods for fetching data.
+ */
 interface AsyncResource
 {
     /**
@@ -16,7 +19,7 @@ interface AsyncResource
     public function getProviderClassName(): string;
 
     /**
-     * Fetches data from the provider using the the specified connector and presents its data as an enumerable series.
+     * Fetches data using the the specified connector and presents its data as an enumerable series.
      *
      * @param ImportConnector $connector Connector.
      *

src/Provider/Resource/ProviderResource.php

@@ -6,7 +6,7 @@
 use ScriptFUSION\Porter\Connector\ImportConnector;
 
 /**
- * Defines methods for fetching data from a specific provider resource.
+ * Defines methods for fetching data.
  */
 interface ProviderResource
 {
@@ -18,7 +18,7 @@ interface ProviderResource
     public function getProviderClassName(): string;
 
     /**
-     * Fetches data from the provider using the the specified connector and presents it as an iterable series.
+     * Fetches data using the the specified connector and presents it as an iterable series.
      *
      * @param ImportConnector $connector Connector.
      *

src/Specification/AsyncImportSpecification.php

@@ -6,16 +6,20 @@
 use ScriptFUSION\Porter\Connector\Recoverable\ExponentialAsyncDelayRecoverableExceptionHandler;
 use ScriptFUSION\Porter\Connector\Recoverable\RecoverableExceptionHandler;
 use ScriptFUSION\Porter\Provider\Resource\AsyncResource;
-use ScriptFUSION\Porter\Transform\AnysyncTransformer;
 use ScriptFUSION\Porter\Transform\AsyncTransformer;
 
 /**
- * Specifies which resource to import asynchronously and how the data should be transformed.
+ * Specifies which resource to import asynchronously, how it should be imported and how the data will be transformed.
  */
 class AsyncImportSpecification extends Specification
 {
     private $asyncResource;
 
+    /**
+     * Initializes this instance with the specified asynchronous resource.
+     *
+     * @param AsyncResource $resource Asynchronous resource.
+     */
     public function __construct(AsyncResource $resource)
     {
         $this->asyncResource = $resource;
@@ -30,20 +34,19 @@ public function __clone()
         parent::__clone();
     }
 
+    /**
+     * Gets the asynchronous resource to import.
+     *
+     * @return AsyncResource Asynchronous resource.
+     */
     final public function getAsyncResource(): AsyncResource
     {
         return $this->asyncResource;
     }
 
-    final public function addTransformer(AnysyncTransformer $transformer): Specification
+    final public function addTransformer(AsyncTransformer $transformer): self
     {
-        if (!$transformer instanceof AsyncTransformer) {
-            throw new IncompatibleTransformerException(
-                'Transformer does not implement interface: ' . AsyncTransformer::class . '.'
-            );
-        }
-
-        return parent::addTransformer($transformer);
+        return parent::addAnyTransformer($transformer);
     }
 
     protected static function createDefaultRecoverableExceptionHandler(): RecoverableExceptionHandler

src/Specification/ImportSpecification.php

@@ -6,19 +6,20 @@
 use ScriptFUSION\Porter\Connector\Recoverable\ExponentialSleepRecoverableExceptionHandler;
 use ScriptFUSION\Porter\Connector\Recoverable\RecoverableExceptionHandler;
 use ScriptFUSION\Porter\Provider\Resource\ProviderResource;
-use ScriptFUSION\Porter\Transform\AnysyncTransformer;
 use ScriptFUSION\Porter\Transform\Transformer;
 
 /**
- * Specifies which resource to import and how the data should be transformed.
+ * Specifies which resource to import, how it should be imported and how the data will be transformed.
  */
 class ImportSpecification extends Specification
 {
-    /**
-     * @var ProviderResource
-     */
     private $resource;
 
+    /**
+     * Initializes this instance with the specified resource.
+     *
+     * @param ProviderResource $resource Resource.
+     */
     public function __construct(ProviderResource $resource)
     {
         $this->resource = $resource;
@@ -34,22 +35,25 @@ public function __clone()
     }
 
     /**
-     * @return ProviderResource
+     * Gets the resource to import.
+     *
+     * @return ProviderResource Resource.
      */
     final public function getResource(): ProviderResource
     {
         return $this->resource;
     }
 
-    final public function addTransformer(AnysyncTransformer $transformer): Specification
+    /**
+     * Adds the specified transformer to the end of the transformers queue.
+     *
+     * @param Transformer $transformer Transformer.
+     *
+     * @return $this
+     */
+    final public function addTransformer(Transformer $transformer): self
     {
-        if (!$transformer instanceof Transformer) {
-            throw new IncompatibleTransformerException(
-                'Transformer does not implement interface: ' . Transformer::class . '.'
-            );
-        }
-
-        return parent::addTransformer($transformer);
+        return parent::addAnyTransformer($transformer);
     }
 
     protected static function createDefaultRecoverableExceptionHandler(): RecoverableExceptionHandler

src/Specification/IncompatibleTransformerException.php

@@ -10,29 +10,17 @@ abstract class Specification
 {
     public const DEFAULT_FETCH_ATTEMPTS = 5;
 
-    /**
-     * @var string|null
-     */
+    /** @var string|null */
     private $providerName;
 
-    /**
-     * @var AnysyncTransformer[]
-     */
+    /** @var AnysyncTransformer[] */
     private $transformers;
 
-    /**
-     * @var mixed
-     */
+    /** @var mixed */
     private $context;
 
-    /**
-     * @var bool
-     */
     private $mustCache = false;
 
-    /**
-     * @var int
-     */
     private $maxFetchAttempts = self::DEFAULT_FETCH_ATTEMPTS;
 
     /**
@@ -95,13 +83,13 @@ final public function getTransformers(): array
     }
 
     /**
-     * Adds the specified transformer.
+     * Adds the specified transformer of any sync type.
      *
      * @param AnysyncTransformer $transformer Transformer.
      *
      * @return $this
      */
-    protected function addTransformer(AnysyncTransformer $transformer): self
+    final protected function addAnyTransformer(AnysyncTransformer $transformer): self
     {
         if ($this->hasTransformer($transformer)) {
             throw new DuplicateTransformerException('Transformer already added.');
@@ -122,7 +110,7 @@ protected function addTransformer(AnysyncTransformer $transformer): self
     final public function addTransformers(array $transformers): self
     {
         foreach ($transformers as $transformer) {
-            $this->addTransformer($transformer);
+            $this->addAnyTransformer($transformer);
         }
 
         return $this;

src/Specification/Specification.php

@@ -5,6 +5,8 @@
 
 /**
  * Marker interface that specifies a transformer that is synchronous, asynchronous or both.
+ *
+ * @internal
  */
 interface AnysyncTransformer
 {