diff --git a/src/contracts/FieldType/Generic/Type.php b/src/contracts/FieldType/Generic/Type.php
index aa0028cd67..55c61b8ab1 100644
--- a/src/contracts/FieldType/Generic/Type.php
+++ b/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:
- *
+ * ```
* protected function createValueFromInput( $inputValue )
* {
- * if ( is_array( $inputValue ) )
+ * if (is_array($inputValue))
* {
* $inputValue = \My\FieldType\CookieJar\Value( $inputValue );
* }
*
* return $inputValue;
* }
- *
+ * ```
*
* @param mixed $inputValue
*
@@ -310,15 +310,15 @@ protected function getValueClass(): string
* FieldType class and is named "Value".
*
* Example implementation:
- *
+ * ```
* 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.");
* }
* }
- *
+ * ```
*
* @param mixed $value A value returned by {@see createValueFromInput()}.
*
diff --git a/src/contracts/FieldType/Generic/ValidationError/ConstraintViolationAdapter.php b/src/contracts/FieldType/Generic/ValidationError/ConstraintViolationAdapter.php
index a7f63aa101..0d39e8ccf1 100644
--- a/src/contracts/FieldType/Generic/ValidationError/ConstraintViolationAdapter.php
+++ b/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
{
diff --git a/src/contracts/Limitation/Target/Builder/VersionBuilder.php b/src/contracts/Limitation/Target/Builder/VersionBuilder.php
index baff618ec0..c4738544c0 100644
--- a/src/contracts/Limitation/Target/Builder/VersionBuilder.php
+++ b/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 $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: VersionInfo::STATUS_DRAFT, VersionInfo::STATUS_PUBLISHED, VersionInfo::STATUS_ARCHIVED
+ * 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 $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 $languageCodes
*
- * @return self
+ * @return VersionBuilder
*
* @throws \Ibexa\Contracts\Core\Repository\Exceptions\InvalidArgumentException
*/
diff --git a/src/contracts/Limitation/Type.php b/src/contracts/Limitation/Type.php
index b93aa4a5c4..cb5410d705 100644
--- a/src/contracts/Limitation/Type.php
+++ b/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 @@ public function buildValue(array $limitationValues);
* @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,9 +143,10 @@ public function getCriterion(APILimitationValue $value, APIUserReference $curren
/**
* 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|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();
}
diff --git a/src/contracts/Repository/Values/Content/Query/Criterion.php b/src/contracts/Repository/Values/Content/Query/Criterion.php
index 7e80664698..16e1267357 100644
--- a/src/contracts/Repository/Values/Content/Query/Criterion.php
+++ b/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|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.
*
- *
+ * ```
* // 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
* )
* ]
- *
+ * ```
*
- * @return \Ibexa\Contracts\Core\Repository\Values\Content\Query\Criterion\Operator\Specifications[]
+ * @return array
*/
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
*/
diff --git a/src/contracts/Repository/Values/Content/Query/Criterion/DateMetadata.php b/src/contracts/Repository/Values/Content/Query/Criterion/DateMetadata.php
index 78d5397468..bbfe5f0643 100644
--- a/src/contracts/Repository/Values/Content/Query/Criterion/DateMetadata.php
+++ b/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:
- *
+ * 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')
* );
- *
+ * ```
*/
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)
diff --git a/src/contracts/Repository/Values/Content/Query/Criterion/Operator/Specifications.php b/src/contracts/Repository/Values/Content/Query/Criterion/Operator/Specifications.php
index f22eeb6973..73c61c5d20 100644
--- a/src/contracts/Repository/Values/Content/Query/Criterion/Operator/Specifications.php
+++ b/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
{
diff --git a/src/contracts/Repository/Values/Content/Query/Criterion/UserMetadata.php b/src/contracts/Repository/Values/Content/Query/Criterion/UserMetadata.php
index 13f4775307..85f53a6f24 100644
--- a/src/contracts/Repository/Values/Content/Query/Criterion/UserMetadata.php
+++ b/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:
- *
+ * 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]
* );
- *
+ * ```
*/
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)
{
diff --git a/src/contracts/Search/Capable.php b/src/contracts/Search/Capable.php
index a6504d9595..0451ffda08 100644
--- a/src/contracts/Search/Capable.php
+++ b/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
*/
diff --git a/src/lib/Limitation/LocationLimitationType.php b/src/lib/Limitation/LocationLimitationType.php
index 3c7cd6571f..e0ce4ec2b6 100644
--- a/src/lib/Limitation/LocationLimitationType.php
+++ b/src/lib/Limitation/LocationLimitationType.php
@@ -224,10 +224,9 @@ public function getCriterion(APILimitationValue $value, APIUserReference $curren
}
/**
- * Returns info on valid $limitationValues.
+ * Returns an integer code meaning that the value must be an array listing location IDs.
*
- * @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.
+ * @return int {@see LocationLimitationType::VALUE_SCHEMA_LOCATION_ID}
*/
public function valueSchema()
{
diff --git a/src/lib/Limitation/SubtreeLimitationType.php b/src/lib/Limitation/SubtreeLimitationType.php
index c642ec64e8..3ceb4cee0d 100644
--- a/src/lib/Limitation/SubtreeLimitationType.php
+++ b/src/lib/Limitation/SubtreeLimitationType.php
@@ -258,10 +258,9 @@ public function getCriterion(APILimitationValue $value, APIUserReference $curren
}
/**
- * Returns info on valid $limitationValues.
+ * Returns an integer code meaning that the value must be an array listing location paths.
*
- * @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.
+ * @return int {@see SubtreeLimitationType::VALUE_SCHEMA_LOCATION_PATH}
*/
public function valueSchema()
{