Enhanced contracts' PHPDoc (#463)

For more details see #463

Key changes:

* Enhance `DateMetadata::TRASHED` phpdoc

* Enhance `Criterion::getSpecifications()` phpdoc

* Enhance `Specifications` phpdoc

* Capable.php: Fix phpdoc summary

* VersionBuilder.php: Fix phpdoc summary, arrays and self usages

* ConstraintViolationAdapter's PHPDoc: Add a summary, reword description

* Enhance `Criterion::getSpecifications()` phpdoc

* Enhance `DateMetadata::TRASHED` phpdoc

* Enhance `DateMetadata` phpdoc

* Enhance `UserMetadata` phpdoc

* Enhance `DateMetadata` phpdoc

* Enhance `Capable` phpdoc

* Enhance `Criterion` phpdoc

* Enhance `UserMetadata` phpdoc (fix typo)

* Enhance `UserMetadata` phpdoc

* Enhance `FieldType\Generic\Type` phpdoc

* Enhance `Limitation\Type` phpdoc

* LocationService: Fix count() phpdoc

* Enhance `LocationService` phpdoc

* Enhance `Location` phpdoc

* Enhance `Location` phpdoc: @deprecated can't be nested nor used inline.

* Enhance `Location` phpdoc: Add an internal link

* Enhance `ValueObject` phpdoc

* Enhance `FieldType\Generic\Type` phpdoc: Fix internal links

* Enhance `FieldType\FieldType` phpdoc: Fix code blocks

* `Limitation\Type`: type array keys

* ValueObject: Format desc

Author: adriendupuis

phpstan-baseline.neon

@@ -5140,11 +5140,6 @@ parameters:
 			count: 1
 			path: src/contracts/Limitation/Target/Builder/VersionBuilder.php
 
-		-
-			message: "#^Method Ibexa\\\\Contracts\\\\Core\\\\Limitation\\\\Target\\\\DestinationLocation\\:\\:__construct\\(\\) has parameter \\$properties with no value type specified in iterable type array\\.$#"
-			count: 1
-			path: src/contracts/Limitation/Target/DestinationLocation.php
-
 		-
 			message: "#^Method Ibexa\\\\Contracts\\\\Core\\\\Limitation\\\\Type\\:\\:acceptValue\\(\\) has no return type specified\\.$#"
 			count: 1
@@ -5275,11 +5270,6 @@ parameters:
 			count: 1
 			path: src/contracts/Persistence/Content/Type.php
 
-		-
-			message: "#^Method Ibexa\\\\Contracts\\\\Core\\\\Persistence\\\\Content\\\\Type\\\\FieldDefinition\\:\\:__construct\\(\\) has parameter \\$properties with no value type specified in iterable type array\\.$#"
-			count: 1
-			path: src/contracts/Persistence/Content/Type/FieldDefinition.php
-
 		-
 			message: "#^Method Ibexa\\\\Contracts\\\\Core\\\\Persistence\\\\Content\\\\Type\\\\Handler\\:\\:delete\\(\\) has no return type specified\\.$#"
 			count: 1
@@ -5575,26 +5565,6 @@ parameters:
 			count: 1
 			path: src/contracts/Repository/Decorator/LocationServiceDecorator.php
 
-		-
-			message: "#^Method Ibexa\\\\Contracts\\\\Core\\\\Repository\\\\Decorator\\\\SearchServiceDecorator\\:\\:findContent\\(\\) has parameter \\$languageFilter with no value type specified in iterable type array\\.$#"
-			count: 1
-			path: src/contracts/Repository/Decorator/SearchServiceDecorator.php
-
-		-
-			message: "#^Method Ibexa\\\\Contracts\\\\Core\\\\Repository\\\\Decorator\\\\SearchServiceDecorator\\:\\:findContentInfo\\(\\) has parameter \\$languageFilter with no value type specified in iterable type array\\.$#"
-			count: 1
-			path: src/contracts/Repository/Decorator/SearchServiceDecorator.php
-
-		-
-			message: "#^Method Ibexa\\\\Contracts\\\\Core\\\\Repository\\\\Decorator\\\\SearchServiceDecorator\\:\\:findLocations\\(\\) has parameter \\$languageFilter with no value type specified in iterable type array\\.$#"
-			count: 1
-			path: src/contracts/Repository/Decorator/SearchServiceDecorator.php
-
-		-
-			message: "#^Method Ibexa\\\\Contracts\\\\Core\\\\Repository\\\\Decorator\\\\SearchServiceDecorator\\:\\:findSingle\\(\\) has parameter \\$languageFilter with no value type specified in iterable type array\\.$#"
-			count: 1
-			path: src/contracts/Repository/Decorator/SearchServiceDecorator.php
-
 		-
 			message: "#^Method Ibexa\\\\Contracts\\\\Core\\\\Repository\\\\Decorator\\\\SearchServiceDecorator\\:\\:suggest\\(\\) has no return type specified\\.$#"
 			count: 1
@@ -6865,26 +6835,6 @@ parameters:
 			count: 1
 			path: src/contracts/Repository/PermissionCriterionResolver.php
 
-		-
-			message: "#^Method Ibexa\\\\Contracts\\\\Core\\\\Repository\\\\SearchService\\:\\:findContent\\(\\) has parameter \\$languageFilter with no value type specified in iterable type array\\.$#"
-			count: 1
-			path: src/contracts/Repository/SearchService.php
-
-		-
-			message: "#^Method Ibexa\\\\Contracts\\\\Core\\\\Repository\\\\SearchService\\:\\:findContentInfo\\(\\) has parameter \\$languageFilter with no value type specified in iterable type array\\.$#"
-			count: 1
-			path: src/contracts/Repository/SearchService.php
-
-		-
-			message: "#^Method Ibexa\\\\Contracts\\\\Core\\\\Repository\\\\SearchService\\:\\:findLocations\\(\\) has parameter \\$languageFilter with no value type specified in iterable type array\\.$#"
-			count: 1
-			path: src/contracts/Repository/SearchService.php
-
-		-
-			message: "#^Method Ibexa\\\\Contracts\\\\Core\\\\Repository\\\\SearchService\\:\\:findSingle\\(\\) has parameter \\$languageFilter with no value type specified in iterable type array\\.$#"
-			count: 1
-			path: src/contracts/Repository/SearchService.php
-
 		-
 			message: "#^Method Ibexa\\\\Contracts\\\\Core\\\\Repository\\\\SearchService\\:\\:suggest\\(\\) has no return type specified\\.$#"
 			count: 1
@@ -7265,21 +7215,11 @@ parameters:
 			count: 1
 			path: src/contracts/Repository/Values/Content/Search/SearchResult.php
 
-		-
-			message: "#^Method Ibexa\\\\Contracts\\\\Core\\\\Repository\\\\Values\\\\Content\\\\Search\\\\SearchResult\\:\\:__construct\\(\\) has parameter \\$properties with no value type specified in iterable type array\\.$#"
-			count: 1
-			path: src/contracts/Repository/Values/Content/Search/SearchResult.php
-
 		-
 			message: "#^Class Ibexa\\\\Contracts\\\\Core\\\\Repository\\\\Values\\\\Content\\\\Trash\\\\SearchResult implements generic interface IteratorAggregate but does not specify its types\\: TKey, TValue$#"
 			count: 1
 			path: src/contracts/Repository/Values/Content/Trash/SearchResult.php
 
-		-
-			message: "#^Method Ibexa\\\\Contracts\\\\Core\\\\Repository\\\\Values\\\\Content\\\\Trash\\\\SearchResult\\:\\:__construct\\(\\) has parameter \\$properties with no value type specified in iterable type array\\.$#"
-			count: 1
-			path: src/contracts/Repository/Values/Content/Trash/SearchResult.php
-
 		-
 			message: "#^Class Ibexa\\\\Contracts\\\\Core\\\\Repository\\\\Values\\\\Content\\\\Trash\\\\TrashItemDeleteResultList implements generic interface IteratorAggregate but does not specify its types\\: TKey, TValue$#"
 			count: 1
@@ -7415,26 +7355,11 @@ parameters:
 			count: 1
 			path: src/contracts/Repository/Values/UserPreference/UserPreferenceList.php
 
-		-
-			message: "#^Method Ibexa\\\\Contracts\\\\Core\\\\Repository\\\\Values\\\\ValueObject\\:\\:__construct\\(\\) has parameter \\$properties with no value type specified in iterable type array\\.$#"
-			count: 1
-			path: src/contracts/Repository/Values/ValueObject.php
-
 		-
 			message: "#^Method Ibexa\\\\Contracts\\\\Core\\\\Repository\\\\Values\\\\ValueObject\\:\\:attributes\\(\\) return type has no value type specified in iterable type array\\.$#"
 			count: 1
 			path: src/contracts/Repository/Values/ValueObject.php
 
-		-
-			message: "#^Method Ibexa\\\\Contracts\\\\Core\\\\Repository\\\\Values\\\\ValueObject\\:\\:getProperties\\(\\) has parameter \\$dynamicProperties with no value type specified in iterable type array\\.$#"
-			count: 1
-			path: src/contracts/Repository/Values/ValueObject.php
-
-		-
-			message: "#^Method Ibexa\\\\Contracts\\\\Core\\\\Repository\\\\Values\\\\ValueObject\\:\\:getProperties\\(\\) return type has no value type specified in iterable type array\\.$#"
-			count: 1
-			path: src/contracts/Repository/Values/ValueObject.php
-
 		-
 			message: "#^Parameter \\#2 \\$value of method Ibexa\\\\Contracts\\\\Core\\\\Repository\\\\Values\\\\ValueObject\\:\\:__set\\(\\) expects string, null given\\.$#"
 			count: 1
@@ -20141,7 +20066,7 @@ parameters:
 			path: src/lib/Repository/Mapper/RoleDomainMapper.php
 
 		-
-			message: "#^Parameter \\#1 \\$limitationValues of method Ibexa\\\\Contracts\\\\Core\\\\Limitation\\\\Type\\:\\:buildValue\\(\\) expects array, array\\|null given\\.$#"
+			message: "#^Parameter \\#1 \\$limitationValues of method Ibexa\\\\Contracts\\\\Core\\\\Limitation\\\\Type\\:\\:buildValue\\(\\) expects array\\<int, mixed\\>, array\\|null given\\.$#"
 			count: 2
 			path: src/lib/Repository/Mapper/RoleDomainMapper.php
 
@@ -20321,7 +20246,7 @@ parameters:
 			path: src/lib/Repository/Permission/PermissionResolver.php
 
 		-
-			message: "#^Parameter \\#1 \\$limitationValues of method Ibexa\\\\Contracts\\\\Core\\\\Limitation\\\\Type\\:\\:buildValue\\(\\) expects array, array\\|null given\\.$#"
+			message: "#^Parameter \\#1 \\$limitationValues of method Ibexa\\\\Contracts\\\\Core\\\\Limitation\\\\Type\\:\\:buildValue\\(\\) expects array\\<int, mixed\\>, array\\|null given\\.$#"
 			count: 1
 			path: src/lib/Repository/Permission/PermissionResolver.php
 
@@ -20760,26 +20685,6 @@ parameters:
 			count: 1
 			path: src/lib/Repository/SiteAccessAware/Repository.php
 
-		-
-			message: "#^Method Ibexa\\\\Core\\\\Repository\\\\SiteAccessAware\\\\SearchService\\:\\:findContent\\(\\) has parameter \\$languageFilter with no value type specified in iterable type array\\.$#"
-			count: 1
-			path: src/lib/Repository/SiteAccessAware/SearchService.php
-
-		-
-			message: "#^Method Ibexa\\\\Core\\\\Repository\\\\SiteAccessAware\\\\SearchService\\:\\:findContentInfo\\(\\) has parameter \\$languageFilter with no value type specified in iterable type array\\.$#"
-			count: 1
-			path: src/lib/Repository/SiteAccessAware/SearchService.php
-
-		-
-			message: "#^Method Ibexa\\\\Core\\\\Repository\\\\SiteAccessAware\\\\SearchService\\:\\:findLocations\\(\\) has parameter \\$languageFilter with no value type specified in iterable type array\\.$#"
-			count: 1
-			path: src/lib/Repository/SiteAccessAware/SearchService.php
-
-		-
-			message: "#^Method Ibexa\\\\Core\\\\Repository\\\\SiteAccessAware\\\\SearchService\\:\\:findSingle\\(\\) has parameter \\$languageFilter with no value type specified in iterable type array\\.$#"
-			count: 1
-			path: src/lib/Repository/SiteAccessAware/SearchService.php
-
 		-
 			message: "#^Method Ibexa\\\\Core\\\\Repository\\\\SiteAccessAware\\\\SearchService\\:\\:suggest\\(\\) has no return type specified\\.$#"
 			count: 1
@@ -21195,16 +21100,6 @@ parameters:
 			count: 1
 			path: src/lib/Repository/Values/Content/Content.php
 
-		-
-			message: "#^Method Ibexa\\\\Core\\\\Repository\\\\Values\\\\Content\\\\Content\\:\\:getProperties\\(\\) has parameter \\$dynamicProperties with no value type specified in iterable type array\\.$#"
-			count: 1
-			path: src/lib/Repository/Values/Content/Content.php
-
-		-
-			message: "#^Method Ibexa\\\\Core\\\\Repository\\\\Values\\\\Content\\\\Content\\:\\:getProperties\\(\\) return type has no value type specified in iterable type array\\.$#"
-			count: 1
-			path: src/lib/Repository/Values/Content/Content.php
-
 		-
 			message: "#^Property Ibexa\\\\Core\\\\Repository\\\\Values\\\\Content\\\\Content\\:\\:\\$fieldDefinitionTranslationMap has unknown class eZ\\\\Publish\\\\API\\\\Repository\\\\Values\\\\Content\\\\Field as its type\\.$#"
 			count: 1
@@ -37835,11 +37730,6 @@ parameters:
 			count: 1
 			path: tests/integration/Core/Repository/SearchServiceTest.php
 
-		-
-			message: "#^Method Ibexa\\\\Tests\\\\Integration\\\\Core\\\\Repository\\\\SearchServiceTest\\:\\:testUserMetadataGroupHorizontalFilterContent\\(\\) has parameter \\$queryType with no type specified\\.$#"
-			count: 1
-			path: tests/integration/Core/Repository/SearchServiceTest.php
-
 		-
 			message: "#^Method Ibexa\\\\Tests\\\\Integration\\\\Core\\\\Repository\\\\SearchServiceTest\\:\\:testUserMetadataGroupHorizontalFilterLocation\\(\\) has no return type specified\\.$#"
 			count: 1

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
 {