[PHPDoc] Improved definitions

phpstan-baseline.neon

@@ -7480,21 +7480,6 @@ parameters:
 			count: 1
 			path: src/contracts/Repository/Values/ValueObject.php
 
-		-
-			message: "#^PHPDoc tag @property\\-read has invalid value \\(\\$name\\)\\: Unexpected token \"\\$name\", expected type at offset 60$#"
-			count: 1
-			path: src/contracts/Search/Field.php
-
-		-
-			message: "#^PHPDoc tag @property\\-read has invalid value \\(\\$type\\)\\: Unexpected token \"\\$type\", expected type at offset 109$#"
-			count: 1
-			path: src/contracts/Search/Field.php
-
-		-
-			message: "#^PHPDoc tag @property\\-read has invalid value \\(\\$value\\)\\: Unexpected token \"\\$value\", expected type at offset 84$#"
-			count: 1
-			path: src/contracts/Search/Field.php
-
 		-
 			message: "#^Method Ibexa\\\\Contracts\\\\Core\\\\Search\\\\FieldType\\\\FullTextField\\:\\:__construct\\(\\) has parameter \\$transformationRules with no value type specified in iterable type array\\.$#"
 			count: 1
@@ -22915,16 +22900,6 @@ parameters:
 			count: 1
 			path: src/lib/Search/Legacy/Content/Mapper/FullTextMapper.php
 
-		-
-			message: "#^Access to protected property Ibexa\\\\Contracts\\\\Core\\\\Search\\\\Field\\:\\:\\$type\\.$#"
-			count: 3
-			path: src/lib/Search/Legacy/Content/Mapper/FullTextMapper.php
-
-		-
-			message: "#^Access to protected property Ibexa\\\\Contracts\\\\Core\\\\Search\\\\Field\\:\\:\\$value\\.$#"
-			count: 3
-			path: src/lib/Search/Legacy/Content/Mapper/FullTextMapper.php
-
 		-
 			message: "#^Method Ibexa\\\\Core\\\\Search\\\\Legacy\\\\Content\\\\WordIndexer\\\\Gateway\\:\\:bulkIndex\\(\\) has no return type specified\\.$#"
 			count: 1

src/contracts/FieldType/FieldType.php

@@ -15,15 +15,15 @@
  *
  * Hashes:
  *
- * The {@link toHash()} method in this class is meant to generate a simple
+ * The {@see FieldType::toHash()} method in this class is meant to generate a simple
  * representation of a value of this field type. Hash does here not refer to
  * MD5 or similar hashing algorithms, but rather to hash-map (associative array)
  * type representation. This representation must be
  * usable, to transfer the value over plain text encoding formats, like e.g.
  * XML. As a result, the returned "hash" must either be a scalar value, a hash
  * array (associative array) a pure numeric array or a nested combination of
  * these. It must by no means contain objects, resources or cyclic references.
- * The corresponding {@link fromHash()} method must convert such a
+ * The corresponding {@see FieldType::fromHash()} method must convert such a
  * representation back into a value, which is understood by the FieldType.
  */
 abstract class FieldType
@@ -47,7 +47,7 @@ abstract public function getFieldTypeIdentifier();
      * It will be used to generate content name and url alias if current field
      * is designated to be used in the content name/urlAlias pattern.
      *
-     * The used $value can be assumed to be already accepted by {@link FieldType::acceptValue()}.
+     * The used $value can be assumed to be already accepted by {@see FieldType::acceptValue()}.
      *
      * @param \Ibexa\Contracts\Core\FieldType\Value $value
      * @param \Ibexa\Contracts\Core\Repository\Values\ContentType\FieldDefinition $fieldDefinition
@@ -136,7 +136,7 @@ abstract public function validate(FieldDefinition $fieldDef, Value $value);
      *
      * This methods determines if the given $validatorConfiguration is
      * structurally correct and complies to the validator configuration schema
-     * returned by {@link getValidatorConfigurationSchema()}.
+     * returned by {@see FieldType::getValidatorConfigurationSchema()}.
      *
      * @param mixed $validatorConfiguration
      *
@@ -157,7 +157,7 @@ abstract public function applyDefaultValidatorConfiguration(&$validatorConfigura
      * Validates the fieldSettings of a FieldDefinitionCreateStruct or FieldDefinitionUpdateStruct.
      *
      * This methods determines if the given $fieldSettings are structurally
-     * correct and comply to the settings schema returned by {@link * getSettingsSchema()}.
+     * correct and comply to the settings schema returned by {@see FieldType::getSettingsSchema()}.
      *
      * @param mixed $fieldSettings
      *
@@ -210,9 +210,9 @@ abstract public function getEmptyValue();
     /**
      * Returns if the given $value is considered empty by the field type.
      *
-     * Usually, only the value returned by {@link getEmptyValue()} is
+     * Usually, only the value returned by {@see FieldType::getEmptyValue()} is
      * considered empty. The given $value can be safely assumed to have already
-     * been processed by {@link acceptValue()}.
+     * been processed by {@see FieldType::acceptValue()}.
      *
      * @param \Ibexa\Contracts\Core\FieldType\Value $value
      *
@@ -232,7 +232,7 @@ abstract public function isEmptyValue(Value $value);
      * format.
      *
      * Note that this method must also cope with the empty value for the field
-     * type as e.g. returned by {@link getEmptyValue()}.
+     * type as e.g. returned by {@see FieldType::getEmptyValue()}.
      *
      * @throws \Ibexa\Contracts\Core\Repository\Exceptions\InvalidArgumentException if the parameter is not of the supported value sub type
      * @throws \Ibexa\Contracts\Core\Repository\Exceptions\InvalidArgumentException if the value does not match the expected structure
@@ -246,8 +246,8 @@ abstract public function acceptValue($inputValue);
     /**
      * Converts an $hash to the Value defined by the field type.
      *
-     * This is the reverse operation to {@link toHash()}. At least the hash
-     * format generated by {@link toHash()} must be converted in reverse.
+     * This is the reverse operation to {@see FieldType::toHash()}. At least the hash
+     * format generated by {@see FieldType::toHash()} must be converted in reverse.
      * Additional formats might be supported in the rare case that this is
      * necessary. See the class description for more details on a hash format.
      *
@@ -285,7 +285,7 @@ abstract public function fieldSettingsToHash($fieldSettings);
     /**
      * Converts the given $fieldSettingsHash to field settings of the type.
      *
-     * This is the reverse operation of {@link fieldSettingsToHash()}.
+     * This is the reverse operation of {@see FieldType::fieldSettingsToHash()}.
      * See the class description for more details on a hash format.
      *
      * @param array|scalar|null $fieldSettingsHash

src/contracts/FieldType/GatewayBasedStorage.php

@@ -37,15 +37,15 @@ public function __construct(StorageGatewayInterface $gateway)
      * This method is used exclusively by Legacy Storage to copy external data of existing field in main language to
      * the untranslatable field not passed in create or update struct, but created implicitly in storage layer.
      *
-     * By default the method falls back to the {@link \Ibexa\Contracts\Core\FieldType\FieldStorage::storeFieldData()}.
+     * By default the method falls back to the {@see \Ibexa\Contracts\Core\FieldType\FieldStorage::storeFieldData()}.
      * External storages implement this method as needed.
      *
      * @param \Ibexa\Contracts\Core\Persistence\Content\VersionInfo $versionInfo
      * @param \Ibexa\Contracts\Core\Persistence\Content\Field $field
      * @param \Ibexa\Contracts\Core\Persistence\Content\Field $originalField
      * @param array $context
      *
-     * @return bool|null Same as {@link \Ibexa\Contracts\Core\FieldType\FieldStorage::storeFieldData()}.
+     * @return bool|null Same as {@see \Ibexa\Contracts\Core\FieldType\FieldStorage::storeFieldData()}.
      */
     public function copyLegacyField(VersionInfo $versionInfo, Field $field, Field $originalField, array $context)
     {

src/contracts/Limitation/Type.php

@@ -57,7 +57,7 @@ public function acceptValue(APILimitationValue $limitationValue);
     /**
      * Makes sure LimitationValue->limitationValues is valid according to valueSchema().
      *
-     * Make sure {@link acceptValue()} is checked first!
+     * Make sure {@see Type::acceptValue()} is checked first.
      *
      * @param \Ibexa\Contracts\Core\Repository\Values\User\Limitation $limitationValue
      *

src/contracts/Persistence/Content/ContentInfo.php

@@ -10,7 +10,7 @@
 
 /**
  * This class provides all version independent information of the content object.
- * It is similar to {@link \Ibexa\Contracts\Core\Repository\Values\Content\ContentInfo}, but for the persistence layer.
+ * It is similar to {@see \Ibexa\Contracts\Core\Repository\Values\Content\ContentInfo}, but for the persistence layer.
  * Thus it only contains raw data.
  */
 class ContentInfo extends ValueObject

src/contracts/Persistence/Content/Location.php

@@ -73,9 +73,11 @@ class Location extends ValueObject
     public $remoteId;
 
     /**
-     * ID of the corresponding {@link \Ibexa\Contracts\Core\Persistence\Content}.
+     * Content ID.
      *
-     * @var mixed Content ID.
+     * ID of the corresponding {@see \Ibexa\Contracts\Core\Persistence\Content}.
+     *
+     * @var int
      */
     public $contentId;
 

src/contracts/Persistence/Content/Location/CreateStruct.php

@@ -45,18 +45,22 @@ class CreateStruct extends ValueObject
     public $remoteId;
 
     /**
-     * ID of the corresponding {@link Content}.
+     * Content ID.
      *
-     * @var mixed Content ID.
+     * ID of the corresponding {@see \Ibexa\Contracts\Core\Repository\Values\Content\Content}.
+     *
+     * @var int
      */
     public $contentId;
 
     /**
-     * version of the corresponding {@link Content}.
+     * Content version.
+     *
+     * Version of the corresponding {@see \Ibexa\Contracts\Core\Repository\Values\Content\Content}.
      *
      * @todo Rename to $contentVersionNo?
      *
-     * @var int Content version.
+     * @var int
      */
     public $contentVersion;
 

src/contracts/Persistence/Content/Type.php

@@ -103,8 +103,9 @@ class Type extends ValueObject
     public $remoteId;
 
     /**
-     * URL alias schema
-     * Same as {@link \Ibexa\Contracts\Core\Persistence\Content\Type::$nameSchema}.
+     * URL alias schema.
+     *
+     * Same as {@see \Ibexa\Contracts\Core\Persistence\Content\Type::$nameSchema}.
      * If nothing is provided, $nameSchema will be used instead.
      *
      * @var string

src/contracts/Persistence/Content/Type/Handler.php

@@ -173,7 +173,9 @@ public function delete($contentTypeId, $status);
     public function createDraft($modifierId, $contentTypeId);
 
     /**
-     * Copy a Type incl fields and group-relations from a given status to a new Type with status {@link Type::STATUS_DRAFT}.
+     * Copy a Type to a new Type with status Draft.
+     *
+     * Copy a Type incl fields and group-relations from a given status to a new Type with status {@see \Ibexa\Contracts\Core\Persistence\Content\Type::STATUS_DRAFT}.
      *
      * New content type will have $userId as creator / modifier, created / modified should be updated, new remoteId created
      * and identifier should be 'copy_of_<originalBaseIdentifier>_<newTypeId>' or another unique string.

src/contracts/Persistence/Content/VersionInfo.php

@@ -37,7 +37,7 @@ class VersionInfo extends ValueObject
     /**
      * Version number.
      *
-     * In contrast to {@link $id}, this is the version number, which only
+     * In contrast to {@see VersionInfo::$id}, this is the version number, which only
      * increments in scope of a single Content object.
      *
      * @var int

src/contracts/Repository/ContentService.php

@@ -215,7 +215,7 @@ public function loadContentListByContentInfo(array $contentInfoList, array $lang
      * @throws \Ibexa\Contracts\Core\Repository\Exceptions\ContentValidationException if a required field is missing or is set to an empty value
      *
      * @param \Ibexa\Contracts\Core\Repository\Values\Content\ContentCreateStruct $contentCreateStruct
-     * @param \Ibexa\Contracts\Core\Repository\Values\Content\LocationCreateStruct[] $locationCreateStructs an array of {@link \Ibexa\Contracts\Core\Repository\Values\Content\LocationCreateStruct} for each location parent under which a location should be created for the content
+     * @param \Ibexa\Contracts\Core\Repository\Values\Content\LocationCreateStruct[] $locationCreateStructs an array of {@see \Ibexa\Contracts\Core\Repository\Values\Content\LocationCreateStruct} for each location parent under which a location should be created for the content
      *                                                                                                While optional, it's highly recommended to use Locations for content as a lot of features in the system is usually tied to the tree structure (including default Role policies).
      * @param string[]|null $fieldIdentifiersToValidate List of field identifiers for partial validation or null
      *                      for case of full validation. Empty identifiers array is equal to no validation.
@@ -227,7 +227,7 @@ public function createContent(ContentCreateStruct $contentCreateStruct, array $l
     /**
      * Updates the metadata.
      *
-     * (see {@link ContentMetadataUpdateStruct}) of a content object - to update fields use updateContent
+     * See {@see ContentMetadataUpdateStruct} of a content object - to update fields use updateContent
      *
      * @throws \Ibexa\Contracts\Core\Repository\Exceptions\UnauthorizedException if the user is not allowed to update the content meta data
      * @throws \Ibexa\Contracts\Core\Repository\Exceptions\InvalidArgumentException if the remoteId in $contentMetadataUpdateStruct is set but already exists
@@ -280,7 +280,7 @@ public function createContentDraft(
      *
      * @param \Ibexa\Contracts\Core\Repository\Values\User\User $user The user to load drafts for, if defined, otherwise drafts for current-user
      *
-     * @return int The number of drafts ({@link VersionInfo}) owned by the given user
+     * @return int The number of drafts ({@see VersionInfo}) owned by the given user
      *
      * @throws \Ibexa\Contracts\Core\Repository\Exceptions\InvalidArgumentException
      */
@@ -297,7 +297,7 @@ public function countContentDrafts(?User $user = null): int;
      *
      * @param \Ibexa\Contracts\Core\Repository\Values\User\User $user The user to load drafts for, if defined, otherwise drafts for current-user
      *
-     * @return \Ibexa\Contracts\Core\Repository\Values\Content\VersionInfo[] the drafts ({@link VersionInfo}) owned by the given user
+     * @return \Ibexa\Contracts\Core\Repository\Values\Content\VersionInfo[] the drafts ({@see VersionInfo}) owned by the given user
      */
     public function loadContentDrafts(?User $user = null): iterable;
 
@@ -377,7 +377,7 @@ public function deleteVersion(VersionInfo $versionInfo): void;
      * @param \Ibexa\Contracts\Core\Repository\Values\Content\ContentInfo $contentInfo
      * @param int|null $status
      *
-     * @return \Ibexa\Contracts\Core\Repository\Values\Content\VersionInfo[] an array of {@link \Ibexa\Contracts\Core\Repository\Values\Content\VersionInfo} sorted by creation date
+     * @return \Ibexa\Contracts\Core\Repository\Values\Content\VersionInfo[] an array of {@see \Ibexa\Contracts\Core\Repository\Values\Content\VersionInfo} sorted by creation date
      */
     public function loadVersions(ContentInfo $contentInfo, ?int $status = null): iterable;
 
@@ -435,7 +435,7 @@ public function countRelations(VersionInfo $versionInfo): int;
      *
      * @param \Ibexa\Contracts\Core\Repository\Values\Content\ContentInfo $contentInfo
      *
-     * @return int The number of reverse relations ({@link Relation})
+     * @return int The number of reverse relations ({@see \Ibexa\Contracts\Core\Repository\Values\Content\Relation})
      */
     public function countReverseRelations(ContentInfo $contentInfo): int;
 
@@ -457,7 +457,7 @@ public function loadReverseRelations(ContentInfo $contentInfo): iterable;
      *
      * The relations come only from published versions of the source content objects.
      * If the user is not allowed to read specific version then UnauthorizedRelationListItem is returned
-     * {@link \Ibexa\Contracts\Core\Repository\Values\Content\RelationList\Item\UnauthorizedRelationListItem}
+     * {@see \Ibexa\Contracts\Core\Repository\Values\Content\RelationList\Item\UnauthorizedRelationListItem}
      *
      * @param \Ibexa\Contracts\Core\Repository\Values\Content\ContentInfo $contentInfo
      * @param int $offset

src/contracts/Repository/ContentTypeService.php

@@ -105,7 +105,7 @@ public function deleteContentTypeGroup(ContentTypeGroup $contentTypeGroup): void
      *
      * @param \Ibexa\Contracts\Core\Repository\Values\ContentType\ContentTypeCreateStruct $contentTypeCreateStruct
      * @param \Ibexa\Contracts\Core\Repository\Values\ContentType\ContentTypeGroup[] $contentTypeGroups Required array of
-     *        {@link ContentTypeGroup} to link type with (must contain one)
+     *        {@see \Ibexa\Contracts\Core\Repository\Values\ContentTypeGroup} to link type with (must contain one)
      *
      * @return \Ibexa\Contracts\Core\Repository\Values\ContentType\ContentTypeDraft
      */
@@ -179,7 +179,7 @@ public function loadContentTypeList(array $contentTypeIds, array $prioritizedLan
      * @param \Ibexa\Contracts\Core\Repository\Values\ContentType\ContentTypeGroup $contentTypeGroup
      * @param string[] $prioritizedLanguages Used as prioritized language code on translated properties of returned object.
      *
-     * @return \Ibexa\Contracts\Core\Repository\Values\ContentType\ContentType[] an array of {@link ContentType} which have status DEFINED
+     * @return \Ibexa\Contracts\Core\Repository\Values\ContentType\ContentType[] an array of {@see \Ibexa\Contracts\Core\Repository\Values\ContentType\ContentType} which have status DEFINED
      */
     public function loadContentTypes(ContentTypeGroup $contentTypeGroup, array $prioritizedLanguages = []): iterable;
 
@@ -201,7 +201,7 @@ public function createContentTypeDraft(ContentType $contentType): ContentTypeDra
     /**
      * Update a content type object.
      *
-     * Does not update fields (fieldDefinitions), use {@link updateFieldDefinition()} to update them.
+     * Does not update fields (fieldDefinitions), use {@see ContentTypeService::updateFieldDefinition()} to update them.
      *
      * @throws \Ibexa\Contracts\Core\Repository\Exceptions\UnauthorizedException if the user is not allowed to update a content type
      * @throws \Ibexa\Contracts\Core\Repository\Exceptions\InvalidArgumentException If the given identifier or remoteId already exists.

src/contracts/Repository/FieldType.php

@@ -123,7 +123,7 @@ public function getEmptyValue();
     /**
      * Returns if the given $value is considered empty by the field type.
      *
-     * Usually, only the value returned by {@link getEmptyValue()} is
+     * Usually, only the value returned by {@see FieldType::getEmptyValue()} is
      * considered empty but that is not always the case.
      *
      * Note: This function assumes that $value is valid so this function can only
@@ -138,7 +138,7 @@ public function isEmptyValue($value): bool;
     /**
      * Converts an $hash to the Value defined by the field type.
      *
-     * This is the reverse operation to {@link toHash()}.
+     * This is the reverse operation to {@see FieldType::toHash()}.
      *
      * @param mixed $hash
      *
@@ -167,7 +167,7 @@ public function fieldSettingsToHash($fieldSettings);
     /**
      * Converts the given $fieldSettingsHash to field settings of the type.
      *
-     * This is the reverse operation of {@link fieldSettingsToHash()}.
+     * This is the reverse operation of {@see FieldType::fieldSettingsToHash()}.
      *
      * @param array|scalar|null $fieldSettingsHash
      *

src/contracts/Repository/LocationService.php

@@ -90,7 +90,7 @@ public function loadLocationByRemoteId(string $remoteId, ?array $prioritizedLang
      * @param \Ibexa\Contracts\Core\Repository\Values\Content\Location $rootLocation
      * @param string[]|null $prioritizedLanguages Used as prioritized language code on translated properties of returned object.
      *
-     * @return \Ibexa\Contracts\Core\Repository\Values\Content\Location[] An array of {@link Location}
+     * @return \Ibexa\Contracts\Core\Repository\Values\Content\Location[] An array of {@see \Ibexa\Contracts\Core\Repository\Values\Content\Location}
      */
     public function loadLocations(ContentInfo $contentInfo, ?Location $rootLocation = null, ?array $prioritizedLanguages = null): iterable;