added phpdocs for better type hinting

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);

src/Compute/v2/Models/Server.php

@@ -394,6 +394,8 @@ public function listAddresses(array $options = []): array
 
     /**
      * Returns Generator for InterfaceAttachment.
+     *
+     * @return \Generator<mixed, \OpenStack\Networking\v2\Models\InterfaceAttachment>
      */
     public function listInterfaceAttachments(array $options = []): \Generator
     {
@@ -541,6 +543,8 @@ public function parseMetadata(ResponseInterface $response): array
 
     /**
      * Returns Generator for SecurityGroups.
+     *
+     * @return \Generator<mixed, \OpenStack\Networking\v2\Extensions\SecurityGroups\Models\SecurityGroup>
      */
     public function listSecurityGroups(): \Generator
     {
@@ -549,6 +553,8 @@ public function listSecurityGroups(): \Generator
 
     /**
      * Returns Generator for VolumeAttachment.
+     *
+     * @return \Generator<mixed, \OpenStack\BlockStorage\v2\Models\VolumeAttachment>
      */
     public function listVolumeAttachments(): \Generator
     {

src/Compute/v2/Service.php

@@ -41,6 +41,7 @@ public function createServer(array $options): Server
      *                           the ID, name and links attributes are returned, saving bandwidth.
      * @param array    $options  {@see \OpenStack\Compute\v2\Api::getServers}
      * @param callable $mapFn    a callable function that will be invoked on every iteration of the list
+     * @return \Generator<mixed, \OpenStack\Compute\v2\Models\Server>
      */
     public function listServers(bool $detailed = false, array $options = [], callable $mapFn = null): \Generator
     {
@@ -73,6 +74,7 @@ public function getServer(array $options = []): Server
      * @param array    $options  {@see \OpenStack\Compute\v2\Api::getFlavors}
      * @param callable $mapFn    a callable function that will be invoked on every iteration of the list
      * @param bool     $detailed set to true to fetch flavors' details
+     * @return \Generator<mixed, \OpenStack\Compute\v2\Models\Flavor>
      */
     public function listFlavors(array $options = [], callable $mapFn = null, bool $detailed = false): \Generator
     {
@@ -112,6 +114,7 @@ public function createFlavor(array $options = []): Flavor
      *
      * @param array    $options {@see \OpenStack\Compute\v2\Api::getImages}
      * @param callable $mapFn   a callable function that will be invoked on every iteration of the list
+     * @return \Generator<mixed, \OpenStack\Compute\v2\Models\Image>
      */
     public function listImages(array $options = [], callable $mapFn = null): \Generator
     {
@@ -139,6 +142,7 @@ public function getImage(array $options = []): Image
      *
      * @param array    $options {@see \OpenStack\Compute\v2\Api::getKeyPairs}
      * @param callable $mapFn   a callable function that will be invoked on every iteration of the list
+     * @return \Generator<mixed, \OpenStack\Compute\v2\Models\Keypair>
      */
     public function listKeypairs(array $options = [], callable $mapFn = null): \Generator
     {
@@ -193,6 +197,7 @@ public function getHypervisorStatistics(): HypervisorStatistic
      *                           the ID, name and links attributes are returned, saving bandwidth.
      * @param array    $options  {@see \OpenStack\Compute\v2\Api::getHypervisors}
      * @param callable $mapFn    a callable function that will be invoked on every iteration of the list
+     * @return \Generator<mixed, \OpenStack\Compute\v2\Models\Hypervisor>
      */
     public function listHypervisors(bool $detailed = false, array $options = [], callable $mapFn = null): \Generator
     {
@@ -216,6 +221,7 @@ public function getHypervisor(array $options = []): Hypervisor
      *
      * @param array    $options {@see \OpenStack\Compute\v2\Api::getHosts}
      * @param callable $mapFn   a callable function that will be invoked on every iteration of the list
+     * @return \Generator<mixed, \OpenStack\Compute\v2\Models\Host>
      */
     public function listHosts(array $options = [], callable $mapFn = null): \Generator
     {
@@ -245,6 +251,7 @@ public function getHost(array $options = []): Host
      *
      * @param array    $options {@see \OpenStack\Compute\v2\Api::getAvailabilityZones}
      * @param callable $mapFn   a callable function that will be invoked on every iteration of the list
+     * @return \Generator<mixed, \OpenStack\Compute\v2\Models\AvailabilityZone>
      */
     public function listAvailabilityZones(array $options = [], callable $mapFn = null): \Generator
     {

src/Identity/v3/Models/Domain.php

@@ -75,6 +75,7 @@ public function delete()
 
     /**
      * @param array $options {@see \OpenStack\Identity\v3\Api::getUserRoles}
+     * @return \Generator<mixed, \OpenStack\Identity\v3\Models\Role>
      */
     public function listUserRoles(array $options = []): \Generator
     {
@@ -115,6 +116,7 @@ public function revokeUserRole(array $options = [])
 
     /**
      * @param array $options {@see \OpenStack\Identity\v3\Api::getGroupRoles}
+     * @return \Generator<mixed, \OpenStack\Identity\v3\Models\Role>
      */
     public function listGroupRoles(array $options = []): \Generator
     {

src/Identity/v3/Models/Group.php

@@ -77,6 +77,7 @@ public function delete()
 
     /**
      * @param array $options {@see \OpenStack\Identity\v3\Api::getGroupUsers}
+     * @return \Generator<mixed, \OpenStack\Identity\v3\Models\User>
      */
     public function listUsers(array $options = []): \Generator
     {

src/Identity/v3/Models/Project.php

@@ -87,6 +87,7 @@ public function delete()
 
     /**
      * @param array $options {@see \OpenStack\Identity\v3\Api::getProjectUserRoles}
+     * @return \Generator<mixed, \OpenStack\Identity\v3\Models\Role>
      */
     public function listUserRoles(array $options = []): \Generator
     {
@@ -127,6 +128,7 @@ public function revokeUserRole(array $options)
 
     /**
      * @param array $options {@see \OpenStack\Identity\v3\Api::getProjectGroupRoles}
+     * @return \Generator<mixed, \OpenStack\Identity\v3\Models\Role>
      */
     public function listGroupRoles(array $options = []): \Generator
     {

src/Identity/v3/Models/User.php

@@ -86,13 +86,19 @@ public function delete()
         $this->execute($this->api->deleteUser(), ['id' => $this->id]);
     }
 
+    /**
+     * @return \Generator<mixed, \OpenStack\Identity\v3\Models\Group>
+     */
     public function listGroups(): \Generator
     {
         $options['id'] = $this->id;
 
         return $this->model(Group::class)->enumerate($this->api->getUserGroups(), $options);
     }
 
+    /**
+     * @return \Generator<mixed, \OpenStack\Identity\v3\Models\Project>
+     */
     public function listProjects(): \Generator
     {
         return $this->model(Project::class)->enumerate($this->api->getUserProjects(), ['id' => $this->id]);

src/Identity/v3/Service.php

@@ -128,6 +128,7 @@ public function createService(array $options): Models\Service
      * will need to use retrieve() to pull in the full state of the remote resource from the API.
      *
      * @param array $options {@see \OpenStack\Identity\v3\Api::getServices}
+     * @return \Generator<mixed, \OpenStack\Identity\v3\Models\Service>
      */
     public function listServices(array $options = []): \Generator
     {
@@ -172,6 +173,7 @@ public function getEndpoint(string $id): Models\Endpoint
      * will need to use retrieve() to pull in the full state of the remote resource from the API.
      *
      * @param array $options {@see \OpenStack\Identity\v3\Api::getEndpoints}
+     * @return \Generator<mixed, \OpenStack\Identity\v3\Models\Endpoint>
      */
     public function listEndpoints(array $options = []): \Generator
     {
@@ -194,6 +196,7 @@ public function createDomain(array $options): Models\Domain
      * will need to use retrieve() to pull in the full state of the remote resource from the API.
      *
      * @param array $options {@see \OpenStack\Identity\v3\Api::getDomains}
+     * @return \Generator<mixed, \OpenStack\Identity\v3\Models\Domain>
      */
     public function listDomains(array $options = []): \Generator
     {
@@ -227,6 +230,7 @@ public function createProject(array $options): Models\Project
      * will need to use retrieve() to pull in the full state of the remote resource from the API.
      *
      * @param array $options {@see \OpenStack\Identity\v3\Api::getProjects}
+     * @return \Generator<mixed, \OpenStack\Identity\v3\Models\Project>
      */
     public function listProjects(array $options = []): \Generator
     {
@@ -260,6 +264,7 @@ public function createUser(array $options): Models\User
      * will need to use retrieve() to pull in the full state of the remote resource from the API.
      *
      * @param array $options {@see \OpenStack\Identity\v3\Api::getUsers}
+     * @return \Generator<mixed, \OpenStack\Identity\v3\Models\User>
      */
     public function listUsers(array $options = []): \Generator
     {
@@ -293,6 +298,7 @@ public function createGroup(array $options): Models\Group
      * will need to use retrieve() to pull in the full state of the remote resource from the API.
      *
      * @param array $options {@see \OpenStack\Identity\v3\Api::getGroups}
+     * @return \Generator<mixed, \OpenStack\Identity\v3\Models\Group>
      */
     public function listGroups(array $options = []): \Generator
     {
@@ -324,6 +330,8 @@ public function createCredential(array $options): Models\Credential
      * Returns a generator which will yield a collection of credential objects. The elements which generators yield can
      * be accessed using a foreach loop. Often the API will not return the full state of the resource in collections;
      * you will need to use retrieve() to pull in the full state of the remote resource from the API.
+     *
+     * @return \Generator<mixed, \OpenStack\Identity\v3\Models\Credential>
      */
     public function listCredentials(): \Generator
     {
@@ -357,6 +365,7 @@ public function createRole(array $options): Models\Role
      * will need to use retrieve() to pull in the full state of the remote resource from the API.
      *
      * @param array $options {@see \OpenStack\Identity\v3\Api::getRoles}
+     * @return \Generator<mixed, \OpenStack\Identity\v3\Models\Role>
      */
     public function listRoles(array $options = []): \Generator
     {
@@ -369,6 +378,7 @@ public function listRoles(array $options = []): \Generator
      * collections; you will need to use retrieve() to pull in the full state of the remote resource from the API.
      *
      * @param array $options {@see \OpenStack\Identity\v3\Api::getRoleAssignments}
+     * @return \Generator<mixed, \OpenStack\Identity\v3\Models\Assignment>
      */
     public function listRoleAssignments(array $options = []): \Generator
     {
@@ -391,6 +401,7 @@ public function createPolicy(array $options): Models\Policy
      * will need to use retrieve() to pull in the full state of the remote resource from the API.
      *
      * @param array $options {@see \OpenStack\Identity\v3\Api::getPolicies}
+     * @return \Generator<mixed, \OpenStack\Identity\v3\Models\Policy>
      */
     public function listPolicies(array $options = []): \Generator
     {

src/Images/v2/Models/Image.php

@@ -115,6 +115,9 @@ public function populateFromArray(array $data): self
         return $this;
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function create(array $data): Creatable
     {
         $response = $this->execute($this->api->postImages(), $data);
@@ -213,6 +216,9 @@ public function addMember($memberId): Member
         return $this->model(Member::class, ['imageId' => $this->id, 'id' => $memberId])->create([]);
     }
 
+    /**
+     * @return \Generator<mixed, \OpenStack\Images\v2\Models\Member>
+     */
     public function listMembers(): \Generator
     {
         return $this->model(Member::class)->enumerate($this->api->getImageMembers(), ['imageId' => $this->id]);

src/Images/v2/Models/Member.php

@@ -54,6 +54,9 @@ protected function getAliases(): array
         ];
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function create(array $userOptions): Creatable
     {
         $response = $this->executeWithState($this->api->postImageMembers());