Enhance PHPDoc

src/contracts/FieldType/Generic/Type.php

@@ -263,17 +263,17 @@ final public function acceptValue($inputValue): Value
      * This is an operation method for {@see acceptValue()}.
      *
      * Example implementation:
-     * <code>
+     * ```
      *  protected function createValueFromInput( $inputValue )
      *  {
-     *      if ( is_array( $inputValue ) )
+     *      if (is_array($inputValue))
      *      {
      *          $inputValue = \My\FieldType\CookieJar\Value( $inputValue );
      *      }
      *
      *      return $inputValue;
      *  }
-     * </code>
+     * ```
      *
      * @param mixed $inputValue
      *
@@ -310,15 +310,15 @@ protected function getValueClass(): string
      * 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()}.
      *

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;
 
     /**
@@ -92,7 +123,7 @@
      * @param \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/Values/Content/Query/Criterion.php

@@ -44,13 +44,15 @@ abstract class Criterion implements CriterionInterface
     public $valueData;
 
     /**
-     * Performs operator validation based on the Criterion specifications returned by {@see getSpecifications()}.
+     * Creates a Criterion.
+     *
+     * Performs operator validation based on the Criterion specifications returned by {@see Criterion::getSpecifications()}.
      *
      * @param string|null $target The target the Criterion applies to: metadata identifier, field identifier...
      * @param string|null $operator
-     *        The operator the Criterion uses. If null is given, will default to Operator::IN if $value is an array,
-     *        Operator::EQ if it is not.
-     * @param scalar[]|scalar $value
+     *        The operator the Criterion uses. If null is given, will default to {@see Operator::IN} if $value is an array,
+     *        {@see Operator::EQ} if it isn't.
+     * @param array<int, scalar>|scalar $value
      * @param \Ibexa\Contracts\Core\Repository\Values\Content\Query\Criterion\Value|null $valueData
      *
      * @todo Add a dedicated exception
@@ -118,12 +120,12 @@ public function __construct(?string $target, ?string $operator, $value, ?Value $
      *
      * Returns the combination of the Criterion's supported operator/value,
      * as an array of {@see \Ibexa\Contracts\Core\Repository\Values\Content\Query\Criterion\Operator\Specifications} objects
-     * - Operator is one supported Operator, as an Operator::* constant
-     * - ValueType is the type of input value this operator requires, either array or single
-     * - SupportedTypes is an array of types the operator will accept
-     * - ValueCountLimitation is an integer saying how many values are expected.
+     * - {@see Specifications::$operator} is a supported {@see Operator} constant.
+     * - {@see Specifications::$valueFormat} is the type of input value this operator requires, either array ({@see Specifications::FORMAT_ARRAY}) or single ({@see Specifications::FORMAT_SINGLE}).
+     * - {@see Specifications::$valueTypes} are bitwise flags of types the operator will accept ({@see Specifications::TYPE_BOOLEAN}, {@see Specifications::TYPE_INTEGER}, and/or {@see Specifications::TYPE_STRING}).
+     * - {@see Specifications::$valueCount} is an integer saying how many values are expected.
      *
-     * <code>
+     * ```
      * // IN and EQ are supported
      * return [
      *     // The EQ operator expects a single value, either as an integer or a string
@@ -139,16 +141,16 @@ public function __construct(?string $target, ?string $operator, $value, ?Value $
      *         Specifications::TYPE_INTEGER | Specifications::TYPE_STRING
      *     )
      * ]
-     * </code>
+     * ```
      *
-     * @return \Ibexa\Contracts\Core\Repository\Values\Content\Query\Criterion\Operator\Specifications[]
+     * @return array<int, \Ibexa\Contracts\Core\Repository\Values\Content\Query\Criterion\Operator\Specifications>
      */
     abstract public function getSpecifications(): array;
 
     /**
      * Returns a callback that checks the values types depending on the operator specifications.
      *
-     * @param int $valueTypes The accepted values, as a bit field of Specifications::TYPE_* constants
+     * @param int $valueTypes The accepted values, as a bit field of {@see Specifications}::TYPE_* constants
      *
      * @return callable
      */

src/contracts/Repository/Values/Content/Query/Criterion/DateMetadata.php

@@ -18,19 +18,19 @@
  * A criterion that matches content based on one of the date metadata (created or modified).
  *
  * Supported Operators:
- * EQ, IN: matches content whose date is or belongs to a list of timestamps
- * GT, GTE: matches content whose date is greater than/greater than or equals the given timestamp
- * LT, LTE: matches content whose date is lower than/lower than or equals the given timestamp
- * BETWEEN: matches content whose date is between (included) the TWO given timestamps
+ * - {@see Operator::EQ EQ}, {@see Operator::IN IN}: matches content whose date is or belongs to a list of timestamps.
+ * - {@see Operator::GT GT}, {@see Operator::GTE GTE}: matches content whose date is greater than/greater than or equals the given timestamp.
+ * - {@see Operator::LT LT}, {@see Operator::LTE LTE}: matches content whose date is lower than/lower than or equals the given timestamp.
+ * - {@see Operator::BETWEEN BETWEEN}: matches content whose date is between TWO (included) given timestamps.
  *
- * Example:
- * <code>
+ * The following example is a criterion for contents created yesterday or today:
+ * ```
  * $createdCriterion = new Criterion\DateMetadata(
  *     Criterion\DateMetadata::CREATED,
- *     Operator::GTE,
- *     strtotime( 'yesterday' )
+ *     Criterion\Operator::GTE,
+ *     strtotime('yesterday')
  * );
- * </code>
+ * ```
  */
 class DateMetadata extends Criterion implements TrashCriterion, FilteringCriterion
 {
@@ -41,7 +41,9 @@ class DateMetadata extends Criterion implements TrashCriterion, FilteringCriteri
     public const PUBLISHED = 'published';
 
     /**
-     * (applies to TrashService::findTrashItems only).
+     * To search for contents based on when they have been sent to trash.
+     *
+     * Applies to {@see \Ibexa\Contracts\Core\Repository\TrashService::findTrashItems()} only.
      */
     public const TRASHED = 'trashed';
 
@@ -53,12 +55,12 @@ class DateMetadata extends Criterion implements TrashCriterion, FilteringCriteri
     ];
 
     /**
-     * Creates a new DateMetadata criterion on $metadata.
+     * Creates a new DateMetadata criterion.
      *
      * @throws \InvalidArgumentException If target is unknown
      *
-     * @param string $target One of DateMetadata::CREATED, DateMetadata::MODIFIED or DateMetadata::TRASHED (applies to TrashService::findTrashItems only)
-     * @param string $operator One of the Operator constants
+     * @param string $target One of {@see DateMetadata::CREATED}, {@see DateMetadata::MODIFIED}, or {@see DateMetadata::TRASHED} (applies to {@see \Ibexa\Contracts\Core\Repository\TrashService::findTrashItems()} only)
+     * @param string $operator One of the {@see Operator} constants
      * @param mixed $value The match value, either as an array of as a single value, depending on the operator
      */
     public function __construct(string $target, string $operator, $value)

src/contracts/Repository/Values/Content/Query/Criterion/Operator/Specifications.php

@@ -11,9 +11,7 @@
 /**
  * This class is used by Criteria to describe which operators they support.
  *
- * Instances of this class are returned in an array by the Criterion::getSpecifications() method
- *
- * @see \Ibexa\Contracts\Core\Repository\Values\Content\Query\Criterion::getSpecifications()
+ * Instances of this class are returned in an array by the {@see \Ibexa\Contracts\Core\Repository\Values\Content\Query\Criterion::getSpecifications()} method.
  */
 class Specifications
 {

src/contracts/Repository/Values/Content/Query/Criterion/UserMetadata.php

@@ -19,16 +19,16 @@
  * group, modifier).
  *
  * Supported Operators:
- * EQ, IN: Matches the provided user ID(s) against the user IDs in the database
+ * - {@see Operator::EQ EQ}, {@see Operator::IN IN}: Matches the provided user ID(s) against the user IDs in the database.
  *
- * Example:
- * <code>
+ * The following example is a criterion for contents owned by a user with ID 10 or 14:
+ * ```
  * $createdCriterion = new Criterion\UserMetadata(
  *     Criterion\UserMetadata::OWNER,
- *     Operator::IN,
- *     array( 10, 14 )
+ *     Criterion\Operator::IN,
+ *     [10, 14]
  * );
- * </code>
+ * ```
  */
 class UserMetadata extends Criterion implements TrashCriterion, FilteringCriterion
 {
@@ -48,13 +48,13 @@ class UserMetadata extends Criterion implements TrashCriterion, FilteringCriteri
     public const MODIFIER = 'modifier';
 
     /**
-     * Creates a new UserMetadata criterion on $metadata.
+     * Creates a new UserMetadata criterion.
      *
      * @throws \InvalidArgumentException If target is unknown
      *
-     * @param string $target One of UserMetadata::OWNER, UserMetadata::GROUP or UserMetadata::MODIFIED
-     * @param string|null $operator The operator the Criterion uses. If null is given, will default to Operator::IN if $value is an array, Operator::EQ if it is not.
-     * @param mixed $value The match value, either as an array of as a single value, depending on the operator
+     * @param string $target One of {@see UserMetadata::OWNER}, {@see UserMetadata::GROUP}, or {@see UserMetadata::MODIFIER}.
+     * @param string|null $operator The operator the Criterion uses. If null is given, will default to {@see Operator::IN} if $value is an array, {@see Operator::EQ} if it isn't.
+     * @param mixed $value The match value, either as an array of as a single value, depending on the operator.
      */
     public function __construct(string $target, ?string $operator, $value)
     {