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