added phpdocs for better type hinting (#376)

Author: k0ka

src/BlockStorage/v2/Models/Snapshot.php

@@ -84,6 +84,8 @@ public function retrieve()
     }
 
     /**
+     * {@inheritdoc}
+     *
      * @param array $userOptions {@see \OpenStack\BlockStorage\v2\Api::postSnapshots}
      */
     public function create(array $userOptions): Creatable

src/BlockStorage/v2/Models/Volume.php

@@ -110,6 +110,8 @@ public function retrieve()
     }
 
     /**
+     * {@inheritdoc}
+     *
      * @param array $userOptions {@see \OpenStack\BlockStorage\v2\Api::postVolumes}
      */
     public function create(array $userOptions): Creatable

src/BlockStorage/v2/Models/VolumeType.php

@@ -25,6 +25,8 @@ class VolumeType extends OperatorResource implements Listable, Creatable, Update
     protected $resourcesKey = 'volume_types';
 
     /**
+     * {@inheritdoc}
+     *
      * @param array $userOptions {@see \OpenStack\BlockStorage\v2\Api::postTypes}
      */
     public function create(array $userOptions): Creatable

src/BlockStorage/v2/Service.php

@@ -31,6 +31,7 @@ public function createVolume(array $userOptions): Volume
      *
      * @param bool  $detail      if set to TRUE, more information will be returned
      * @param array $userOptions {@see Api::getVolumes}
+     * @return \Generator<mixed, \OpenStack\BlockStorage\v2\Models\Volume>
      */
     public function listVolumes(bool $detail = false, array $userOptions = []): \Generator
     {
@@ -58,6 +59,9 @@ public function createVolumeType(array $userOptions): VolumeType
         return $this->model(VolumeType::class)->create($userOptions);
     }
 
+    /**
+     * @return \Generator<mixed, \OpenStack\BlockStorage\v2\Models\VolumeType>
+     */
     public function listVolumeTypes(): \Generator
     {
         return $this->model(VolumeType::class)->enumerate($this->api->getTypes(), []);
@@ -79,6 +83,9 @@ public function createSnapshot(array $userOptions): Snapshot
         return $this->model(Snapshot::class)->create($userOptions);
     }
 
+    /**
+     * @return \Generator<mixed, \OpenStack\BlockStorage\v2\Models\Snapshot>
+     */
     public function listSnapshots(bool $detail = false, array $userOptions = []): \Generator
     {
         $def = (true === $detail) ? $this->api->getSnapshotsDetail() : $this->api->getSnapshots();

src/Common/Resource/AbstractResource.php

@@ -55,7 +55,7 @@ public function populateFromResponse(ResponseInterface $response)
     /**
      * Populates the current resource from a data array.
      *
-     * @return mixed|void
+     * @return self
      */
     public function populateFromArray(array $array)
     {

src/Common/Resource/Creatable.php

@@ -12,7 +12,7 @@ interface Creatable
     /**
      * Create a new resource according to the configuration set in the options.
      *
-     * @return self
+     * @return static
      */
     public function create(array $userOptions): Creatable;
 }

src/Common/Resource/Listable.php

@@ -22,7 +22,7 @@ interface Listable
      * @param array    $userVals The user values
      * @param callable $mapFn    an optional callback that will be executed on every resource iteration
      *
-     * @returns void
+     * @returns \Generator<mixed, static>
      */
     public function enumerate(array $def, array $userVals = [], callable $mapFn = null);
 }

src/Common/Resource/OperatorResource.php

@@ -68,7 +68,9 @@ private function getResourcesKey(): string
     }
 
     /**
-     * {@inheritdoc}
+     * Creates a generator for enumerating over a collection of resources returned by the request.
+     *
+     * @returns \Generator<mixed, static>
      */
     public function enumerate(array $def, array $userVals = [], callable $mapFn = null): \Generator
     {
@@ -101,6 +103,11 @@ public function enumerate(array $def, array $userVals = [], callable $mapFn = nu
         return $iterator();
     }
 
+    /**
+     * Extracts multiple instances of the current resource from a response.
+     *
+     * @return array<self>
+     */
     public function extractMultipleInstances(ResponseInterface $response, string $key = null): array
     {
         $key           = $key ?: $this->getResourcesKey();

src/Common/Resource/ResourceInterface.php

@@ -15,21 +15,23 @@ interface ResourceInterface
      * All models which represent an API resource should be able to be populated
      * from a {@see ResponseInterface} object.
      *
+     * @param \Psr\Http\Message\ResponseInterface $response
      * @return self
      */
     public function populateFromResponse(ResponseInterface $response);
 
     /**
-     * @return mixed
+     * @return self
      */
     public function populateFromArray(array $data);
 
     /**
-     * @param string $name the name of the model class
+     * @template T of \OpenStack\Common\Resource\ResourceInterface
+     * @param class-string<T> $class the name of the model class
      * @param mixed  $data either a {@see ResponseInterface} or data array that will populate the newly
      *                     created model class
      *
-     * @return \OpenStack\Common\Resource\ResourceInterface
+     * @return T
      */
     public function model(string $class, $data = null): ResourceInterface;
 }

src/Compute/v2/Models/Keypair.php

@@ -75,6 +75,9 @@ public function retrieve()
         $this->populateFromResponse($response);
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function create(array $userOptions): Creatable
     {
         $response = $this->execute($this->api->postKeypair(), $userOptions);