Enhance PHPDoc

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/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}: 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)
     {

src/contracts/Search/Capable.php

@@ -9,6 +9,8 @@
 namespace Ibexa\Contracts\Core\Search;
 
 /**
+ * Capability interface for search engines.
+ *
  * Capability interface for search engines needed for {@see \Ibexa\Contracts\Core\Repository\SearchService::supports()}.
  *
  * @since 6.12 And ported to 6.7.6 for search engine forward compatibility.
@@ -18,7 +20,7 @@ interface Capable
     /**
      * Query for supported capability of currently configured search engine.
      *
-     * @param int $capabilityFlag One of \Ibexa\Contracts\Core\Repository\SearchService::CAPABILITY_* constants.
+     * @param int $capabilityFlag One of {@see \Ibexa\Contracts\Core\Repository\SearchService}::CAPABILITY_* constants.
      *
      * @return bool
      */