Skip to content

Commit

Permalink
[PHPDoc] Fixed erroneous annotations for PHP API reference (#397)
Browse files Browse the repository at this point in the history
For more details see #397

Key changes:

* [PHPDoc] Added missing types for Ibexa\Contracts\Core\Search\Field

* [PHPDoc] Converted link tags to see

* [PHPStan] Aligned PHPStan baseline with the changes

---------

Co-Authored-By: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com>
Co-Authored-By: Andrew Longosz <alongosz@users.noreply.github.com>
  • Loading branch information
3 people authored Jul 4, 2024
1 parent 4ef331b commit e710a6e
Show file tree
Hide file tree
Showing 22 changed files with 65 additions and 79 deletions.
25 changes: 0 additions & 25 deletions phpstan-baseline.neon
Original file line number Diff line number Diff line change
Expand Up @@ -7460,21 +7460,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
Expand Down Expand Up @@ -22895,16 +22880,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
Expand Down
22 changes: 11 additions & 11 deletions src/contracts/FieldType/FieldType.php
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
*
Expand All @@ -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
*
Expand Down Expand Up @@ -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
*
Expand All @@ -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
Expand All @@ -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.
*
Expand Down Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions src/contracts/FieldType/GatewayBasedStorage.php
Original file line number Diff line number Diff line change
Expand Up @@ -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)
{
Expand Down
2 changes: 1 addition & 1 deletion src/contracts/Limitation/Type.php
Original file line number Diff line number Diff line change
Expand Up @@ -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
*
Expand Down
2 changes: 1 addition & 1 deletion src/contracts/Persistence/Content/ContentInfo.php
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 4 additions & 2 deletions src/contracts/Persistence/Content/Location.php
Original file line number Diff line number Diff line change
Expand Up @@ -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;

Expand Down
12 changes: 8 additions & 4 deletions src/contracts/Persistence/Content/Location/CreateStruct.php
Original file line number Diff line number Diff line change
Expand Up @@ -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;

Expand Down
5 changes: 3 additions & 2 deletions src/contracts/Persistence/Content/Type.php
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 3 additions & 1 deletion src/contracts/Persistence/Content/Type/Handler.php
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion src/contracts/Persistence/Content/VersionInfo.php
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
14 changes: 7 additions & 7 deletions src/contracts/Repository/ContentService.php
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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
Expand Down Expand Up @@ -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
*/
Expand All @@ -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;

Expand Down Expand Up @@ -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;

Expand Down Expand Up @@ -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;

Expand All @@ -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
Expand Down
6 changes: 3 additions & 3 deletions src/contracts/Repository/ContentTypeService.php
Original file line number Diff line number Diff line change
Expand Up @@ -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
*/
Expand Down Expand Up @@ -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;

Expand All @@ -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.
Expand Down
6 changes: 3 additions & 3 deletions src/contracts/Repository/FieldType.php
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
*
Expand Down Expand Up @@ -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
*
Expand Down
2 changes: 1 addition & 1 deletion src/contracts/Repository/LocationService.php
Original file line number Diff line number Diff line change
Expand Up @@ -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;

Expand Down
Loading

0 comments on commit e710a6e

Please sign in to comment.