Enhance PHPDoc

src/contracts/FieldType/FieldType.php

@@ -100,20 +100,20 @@ abstract public function getSettingsSchema();
      * It is considered best practice to return a hash map, which contains
      * rudimentary settings structures, like e.g. for the "ezstring" FieldType
      *
-     * <code>
-     *  array(
-     *      'stringLength' => array(
-     *          'minStringLength' => array(
-     *              'type'    => 'int',
-     *              'default' => 0,
-     *          ),
-     *          'maxStringLength' => array(
-     *              'type'    => 'int'
-     *              'default' => null,
-     *          )
-     *      ),
-     *  );
-     * </code>
+     * ```
+     * [
+     *     'stringLength' => [
+     *         'minStringLength' => [
+     *             'type'    => 'int',
+     *             'default' => 0,
+     *         ],
+     *         'maxStringLength' => [
+     *             'type'    => 'int'
+     *             'default' => null,
+     *         ],
+     *     ],
+     * ];
+     * ```
      *
      * @return mixed
      */
@@ -360,22 +360,22 @@ abstract public function fromPersistenceValue(FieldValue $fieldValue);
      *
      * @param \Ibexa\Contracts\Core\FieldType\Value $value
      *
-     * @return array Hash with relation type as key and array of destination content ids as value.
+     * @return array Hash with relation type as key and array of destination content IDs as value.
      *
      * Example:
-     * <code>
-     *  array(
-     *      \Ibexa\Contracts\Core\Repository\Values\Content\Relation::LINK => array(
-     *          "contentIds" => array( 12, 13, 14 ),
-     *          "locationIds" => array( 24 )
-     *      ),
-     *      \Ibexa\Contracts\Core\Repository\Values\Content\Relation::EMBED => array(
-     *          "contentIds" => array( 12 ),
-     *          "locationIds" => array( 24, 45 )
-     *      ),
-     *      \Ibexa\Contracts\Core\Repository\Values\Content\Relation::FIELD => array( 12 )
-     *  )
-     * </code>
+     * ```
+     * [
+     *     \Ibexa\Contracts\Core\Repository\Values\Content\Relation::LINK => [
+     *         'contentIds' => [12, 13, 14],
+     *         'locationIds' => [24]
+     *     ],
+     *     \Ibexa\Contracts\Core\Repository\Values\Content\Relation::EMBED => [
+     *         'contentIds" => [12],
+     *         'locationIds' => [24, 45]
+     *     ],
+     *     \Ibexa\Contracts\Core\Repository\Values\Content\Relation::FIELD => [12]
+     * ]
+     * ```
      */
     abstract public function getRelations(Value $value);
 }

src/contracts/FieldType/Generic/Type.php

@@ -260,20 +260,20 @@ final public function acceptValue($inputValue): Value
      * If given $inputValue could not be converted or is already an instance of dedicate value object,
      * the method should simply return it.
      *
-     * This is an operation method for {@see acceptValue()}.
+     * This is an operation method for {@see Type::acceptValue()}.
      *
      * Example implementation:
-     * <code>
-     *  protected function createValueFromInput( $inputValue )
+     * ```
+     *  protected function createValueFromInput($inputValue)
      *  {
-     *      if ( is_array( $inputValue ) )
+     *      if (is_array($inputValue))
      *      {
-     *          $inputValue = \My\FieldType\CookieJar\Value( $inputValue );
+     *          $inputValue = \My\FieldType\CookieJar\Value($inputValue);
      *      }
      *
      *      return $inputValue;
      *  }
-     * </code>
+     * ```
      *
      * @param mixed $inputValue
      *
@@ -304,23 +304,23 @@ protected function getValueClass(): string
     /**
      * Throws an exception if the given $value is not an instance of the supported value subtype.
      *
-     * This is an operation method for {@see acceptValue()}.
+     * This is an operation method for {@see Type::acceptValue()}.
      *
      * Default implementation expects the value class to reside in the same namespace as its
      * FieldType class and is named "Value".
      *
      * Example implementation:
-     * <code>
+     * ```
      *  protected function checkValueType($value): void
      *  {
-     *      if ( !$inputValue instanceof \My\FieldType\CookieJar\Value ) )
+     *      if (!$inputValue instanceof \My\FieldType\CookieJar\Value))
      *      {
-     *          throw new InvalidArgumentException( "Given value type is not supported." );
+     *          throw new InvalidArgumentException("Given value type isn't supported.");
      *      }
      *  }
-     * </code>
+     * ```
      *
-     * @param mixed $value A value returned by {@see createValueFromInput()}.
+     * @param mixed $value A value returned by {@see Type::createValueFromInput()}.
      *
      * @throws \Ibexa\Contracts\Core\Repository\Exceptions\InvalidArgumentException If the parameter is not an instance of the supported value subtype.
      */

src/contracts/FieldType/Generic/ValidationError/ConstraintViolationAdapter.php

@@ -14,8 +14,10 @@
 use Symfony\Component\Validator\ConstraintViolationInterface;
 
 /**
- * {@see \Symfony\Component\Validator\ConstraintViolationInterface} to
- * {@see \Ibexa\Contracts\Core\FieldType\ValidationError} adapter.
+ * Constraint violation validation error.
+ *
+ * Adapts {@see \Symfony\Component\Validator\ConstraintViolationInterface} to
+ * {@see \Ibexa\Contracts\Core\FieldType\ValidationError}.
  */
 final class ConstraintViolationAdapter implements ValidationErrorInterface
 {

src/contracts/Limitation/Target/Builder/VersionBuilder.php

@@ -14,6 +14,8 @@
 use Ibexa\Core\Base\Exceptions\InvalidArgumentException;
 
 /**
+ * Version builder.
+ *
  * Builder of {@see \Ibexa\Contracts\Core\Limitation\Target\Version} instance.
  */
 final class VersionBuilder
@@ -28,6 +30,8 @@ public function build(): Target\Version
 
     /**
      * @param \Ibexa\Contracts\Core\Repository\Values\Content\Field[] $updatedFields
+     *
+     * @return VersionBuilder
      */
     public function updateFields(array $updatedFields): self
     {
@@ -41,7 +45,7 @@ public function updateFields(array $updatedFields): self
      *
      * @param array $languageCodes
      *
-     * @return self
+     * @return VersionBuilder
      *
      * @throws \Ibexa\Contracts\Core\Repository\Exceptions\InvalidArgumentException
      */
@@ -61,9 +65,9 @@ public function translateToAnyLanguageOf(array $languageCodes): self
     /**
      * Set intent to create Content from unspecified (yet) content type, any from the given list.
      *
-     * @param int[] $contentTypeIds
+     * @param array<int, int> $contentTypeIds
      *
-     * @return self
+     * @return VersionBuilder
      *
      * @throws \Ibexa\Contracts\Core\Repository\Exceptions\InvalidArgumentException
      */
@@ -83,13 +87,13 @@ public function createFromAnyContentTypeOf(array $contentTypeIds): self
     /**
      * Set intent to change Version status.
      *
-     * Supported: <code>VersionInfo::STATUS_DRAFT, VersionInfo::STATUS_PUBLISHED, VersionInfo::STATUS_ARCHIVED</code>
+     * Supported: {@see \Ibexa\Contracts\Core\Repository\Values\Content\VersionInfo::STATUS_DRAFT}, {@see \Ibexa\Contracts\Core\Repository\Values\Content\VersionInfo::STATUS_PUBLISHED}, {@see \Ibexa\Contracts\Core\Repository\Values\Content\VersionInfo::STATUS_ARCHIVED}
      *
      * @see \Ibexa\Contracts\Core\Repository\Values\Content\VersionInfo
      *
      * @param int $status
      *
-     * @return self
+     * @return VersionBuilder
      *
      * @throws \Ibexa\Contracts\Core\Repository\Exceptions\InvalidArgumentException
      */
@@ -114,9 +118,9 @@ public function changeStatusTo(int $status): self
      * Set intent to update Content Version Fields.
      *
      * @param string|null $initialLanguageCode
-     * @param \Ibexa\Contracts\Core\Repository\Values\Content\Field[] $fields
+     * @param array<int, \Ibexa\Contracts\Core\Repository\Values\Content\Field> $fields
      *
-     * @return self
+     * @return VersionBuilder
      */
     public function updateFieldsTo(?string $initialLanguageCode, array $fields): self
     {
@@ -138,9 +142,9 @@ static function (Field $field) {
     /**
      * Set intent to publish, to specified translations, all from the given list.
      *
-     * @param string[] $languageCodes
+     * @param array<int, string> $languageCodes
      *
-     * @return self
+     * @return VersionBuilder
      *
      * @throws \Ibexa\Contracts\Core\Repository\Exceptions\InvalidArgumentException
      */

src/contracts/Limitation/Type.php

@@ -21,26 +21,57 @@
 interface Type
 {
     /**
-     * Constants for return value of {@see evaluate()}.
+     * Access is granted.
      *
-     * Currently ACCESS_ABSTAIN must mean that evaluate does not support the provided $object or $targets,
-     * this is currently only supported by role limitations as policy limitations should not allow this.
+     * Constant for return value of {@see Type::evaluate()}.
      *
      * Note: In future version constant values might change to 1, 0 and -1 as used in Symfony.
      *
      * @since 5.3.2
      */
     public const ACCESS_GRANTED = true;
+
+    /**
+     * The type abstains from voting.
+     *
+     * Constant for return value of {@see Type::evaluate()}.
+     *
+     * Returning ACCESS_ABSTAIN must mean that evaluate does not support the provided $object or $targets,
+     * this is only supported by role limitations as policy limitations should not allow this.
+     *
+     * Note: In future version constant values might change to 1, 0 and -1 as used in Symfony.
+     *
+     * @since 5.3.2
+     */
     public const ACCESS_ABSTAIN = null;
+
+    /**
+     * Access is denied.
+     *
+     * Constant for return value of {@see Type::evaluate()}.
+     *
+     * Note: In future version constant values might change to 1, 0 and -1 as used in Symfony.
+     *
+     * @since 5.3.2
+     */
     public const ACCESS_DENIED = false;
 
     /**
-     * Constants for valueSchema() return values.
+     * Limitation's value must be an array of location IDs.
+     *
+     * Constant for {@see Type::valueSchema()} return values.
      *
-     * Used in cases where a certain value is accepted but the options are to many to return as a hash of options.
      * GUI should typically present option to browse content tree to select limitation value(s).
      */
     public const VALUE_SCHEMA_LOCATION_ID = 1;
+
+    /**
+     * Limitation's value must be an array of location paths.
+     *
+     * Constant for {@see Type::valueSchema()} return values.
+     *
+     * GUI should typically present option to browse content tree to select limitation value(s).
+     */
     public const VALUE_SCHEMA_LOCATION_PATH = 2;
 
     /**
@@ -61,17 +92,17 @@
      *
      * @param \Ibexa\Contracts\Core\Repository\Values\User\Limitation $limitationValue
      *
-     * @return \Ibexa\Contracts\Core\FieldType\ValidationError[]
+     * @return array<int, \Ibexa\Contracts\Core\FieldType\ValidationError>
      */
     public function validate(APILimitationValue $limitationValue);
 
     /**
      * Create the Limitation Value.
      *
-     * The is the method to create values as Limitation type needs value knowledge anyway in acceptValue,
+     * This is the method to create values as Limitation type needs value knowledge anyway in acceptValue,
      * the reverse relation is provided by means of identifier lookup (Value has identifier, and so does RoleService).
      *
-     * @param mixed[] $limitationValues
+     * @param array<int, mixed> $limitationValues
      *
      * @return \Ibexa\Contracts\Core\Repository\Values\User\Limitation
      */
@@ -89,10 +120,10 @@
      * @param \Ibexa\Contracts\Core\Repository\Values\User\Limitation $value
      * @param \Ibexa\Contracts\Core\Repository\Values\User\UserReference $currentUser
      * @param \Ibexa\Contracts\Core\Repository\Values\ValueObject $object
-     * @param \Ibexa\Contracts\Core\Repository\Values\ValueObject[]|null $targets An array of location, parent or "assignment"
+     * @param array<int, \Ibexa\Contracts\Core\Repository\Values\ValueObject>|null $targets An array of location, parent or "assignment"
      *                                                                 objects, if null: none where provided by caller
      *
-     * @return bool|null Returns one of ACCESS_* constants
+     * @return bool|null Returns one of ACCESS_* constants, {@see Type::ACCESS_GRANTED}, {@see Type::ACCESS_ABSTAIN}, or {@see Type::ACCESS_DENIED}.
      */
     public function evaluate(APILimitationValue $value, APIUserReference $currentUser, APIValueObject $object, array $targets = null);
 
@@ -112,11 +143,12 @@
     /**
      * Returns info on valid $limitationValues.
      *
-     * @return mixed[]|int In case of array, a hash with key as valid limitations value and value as human readable name
-     *                     of that option, in case of int on of VALUE_SCHEMA_* constants.
-     *                     Note: The hash might be an instance of Traversable, and not a native php array.
+     * @return array<string, string>|Traversable|int In case of array, a hash with key as valid limitations value and value as human-readable name
+     *                     of that option. Note: The hash might be an instance of Traversable instead of a native PHP array.
+     *                     In case of int, one of VALUE_SCHEMA_* constants. Used in cases where a certain value is accepted
+     *                     but the options are too many to return as a hash of options.
      */
     public function valueSchema();
 }
 
 class_alias(Type::class, 'eZ\Publish\SPI\Limitation\Type');

src/contracts/Repository/LocationService.php

@@ -57,10 +57,10 @@ public function loadLocation(int $locationId, ?array $prioritizedLanguages = nul
      * Returned list of Locations will be filtered by what is found and what current user has access to.
      *
      * @param array $locationIds
-     * @param string[]|null $prioritizedLanguages Filter on and use as prioritized language code on translated properties of returned objects.
+     * @param array<int, string>|null $prioritizedLanguages Filter on and use as prioritized language code on translated properties of returned objects.
      * @param bool|null $useAlwaysAvailable Respect always available flag on content when filtering on $prioritizedLanguages.
      *
-     * @return \Ibexa\Contracts\Core\Repository\Values\Content\Location[]|iterable
+     * @return array<int, \Ibexa\Contracts\Core\Repository\Values\Content\Location>|iterable
      */
     public function loadLocationList(array $locationIds, ?array $prioritizedLanguages = null, ?bool $useAlwaysAvailable = null): iterable;
 
@@ -253,23 +253,25 @@ public function getAllLocationsCount(): int;
      * @param int $limit
      * @param int $offset
      *
-     * @return \Ibexa\Contracts\Core\Repository\Values\Content\Location[]
+     * @return array<int, \Ibexa\Contracts\Core\Repository\Values\Content\Location>
      */
     public function loadAllLocations(int $offset = 0, int $limit = 25): array;
 
     /**
      * Fetch a LocationList from the Repository filtered by the given conditions.
      *
-     * @param string[] $languages a list of language codes to be added as additional constraints.
+     * @param array<int, string>|null $languages a list of language codes to be added as additional constraints.
      *        If skipped, by default, unless SiteAccessAware layer has been disabled, languages set
      *        for a SiteAccess in a current context will be used.
      */
     public function find(Filter $filter, ?array $languages = null): LocationList;
 
     /**
-     * Count total number of items returned by {@see find} method.
+     * Counts total number of items matching the filter.
      *
-     * @param string[] $languages a list of language codes to be added as additional constraints.
+     * Return the count of items that would be returned by {@see LocationService::find()} method.
+     *
+     * @param array<int, string>|null $languages a list of language codes to be added as additional constraints.
      *        If skipped, by default, unless SiteAccessAware layer has been disabled, languages set
      *        for a SiteAccess in a current context will be used.
      */