Skip to content

IBX-4929: Fixed PhpDoc in various places #226

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
adamwojs merged 11 commits into from
May 20, 2023
Merged

IBX-4929: Fixed PhpDoc in various places #226

Show file tree
Hide file tree
Changes from 10 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
9002235
Fix @see usage
adriendupuis Apr 4, 2023
d8e26cc
Repository.php: Moved from @param to @phpstan-param
adriendupuis Apr 5, 2023
832797b
RoleService.php: Fix @since usage
adriendupuis Apr 5, 2023
bee79a5
SearchService.php: Fix @since usage
adriendupuis Apr 5, 2023
7a2dfb5
Repository.php: Fix phpdoc_separation
adriendupuis Apr 7, 2023
0bd5d70
SearchResultAdapter.php: Fix @see vs @link usage
adriendupuis Apr 7, 2023
8e79ab5
Specifications.php: Fix @see usage
adriendupuis Apr 7, 2023
e1c6ddc
Specifications.php: Fix @see usage
adriendupuis Apr 7, 2023
48927b2
SearchResultAdapter.php: @see and @link can NOT be used in summary
adriendupuis Apr 7, 2023
8721389
Update src/contracts/Repository/SearchService.php
adriendupuis Apr 13, 2023
6261143
SearchResultAdapter.php: Rework phpDoc
adriendupuis Apr 19, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions src/contracts/Persistence/Content/Relation.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,11 +51,11 @@ class Relation extends ValueObject
/**
* Type bitmask.
*
* @see \Ibexa\Contracts\Core\Repository\Values\Content\Relation::COMMON,
* \Ibexa\Contracts\Core\Repository\Values\Content\Relation::EMBED,
* \Ibexa\Contracts\Core\Repository\Values\Content\Relation::LINK,
* \Ibexa\Contracts\Core\Repository\Values\Content\Relation::FIELD
* \Ibexa\Contracts\Core\Repository\Values\Content\Relation::ASSET
* @see \Ibexa\Contracts\Core\Repository\Values\Content\Relation::COMMON
* @see \Ibexa\Contracts\Core\Repository\Values\Content\Relation::EMBED
* @see \Ibexa\Contracts\Core\Repository\Values\Content\Relation::LINK
* @see \Ibexa\Contracts\Core\Repository\Values\Content\Relation::FIELD
* @see \Ibexa\Contracts\Core\Repository\Values\Content\Relation::ASSET
*
* @var int
*/
Expand Down
8 changes: 4 additions & 4 deletions src/contracts/Persistence/Content/Relation/CreateStruct.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,10 +44,10 @@ class CreateStruct extends ValueObject
/**
* Type bitmask.
*
* @see \Ibexa\Contracts\Core\Repository\Values\Content\Relation::COMMON,
* \Ibexa\Contracts\Core\Repository\Values\Content\Relation::EMBED,
* \Ibexa\Contracts\Core\Repository\Values\Content\Relation::LINK,
* \Ibexa\Contracts\Core\Repository\Values\Content\Relation::FIELD
* @see \Ibexa\Contracts\Core\Repository\Values\Content\Relation::COMMON
* @see \Ibexa\Contracts\Core\Repository\Values\Content\Relation::EMBED
* @see \Ibexa\Contracts\Core\Repository\Values\Content\Relation::LINK
* @see \Ibexa\Contracts\Core\Repository\Values\Content\Relation::FIELD
*
* @var int
*/
Expand Down
3 changes: 2 additions & 1 deletion src/contracts/Repository/Repository.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,8 @@ interface Repository
*
* @template T
*
* @param callable(\Ibexa\Contracts\Core\Repository\Repository): T $callback
* @phpstan-param callable(\Ibexa\Contracts\Core\Repository\Repository): T $callback
*
* @param \Ibexa\Contracts\Core\Repository\Repository|null $outerRepository Optional, mostly
* for internal use but allows to specify Repository to pass to closure.
*
Expand Down
20 changes: 10 additions & 10 deletions src/contracts/Repository/RoleService.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ interface RoleService
/**
* Creates a new RoleDraft.
*
* @since 6.0
* @since 1.0 eZ Platform 1.0 (ezpublish-kernel 6.0)
Copy link
Member

@alongosz alongosz Apr 17, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should rather be just @since eZ Platform 1.0. Technically we can remove it, but I think it requires more discussion within PHP Team.

Copy link
Contributor Author

@adriendupuis adriendupuis Apr 18, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@alongosz

@since eZ Platform 1.0 causes the log entry Tag "since" with body "@since eZ Platform 1.0" has error.

https://docs.phpdoc.org/3.3/guide/references/phpdoc/tags/since.html defines in @since [<version>] [<description>] the version number argument as optional, but, in fact, it is mandatory with phpDocumentor 3.3.1 which is looking for digit and dots only as first argument.

It's only a log, no element skipped, the tag even renders properly. It could be kept as @since eZ Platform 1.0 with no or minimal annoyance.

Copy link
Member

@alongosz alongosz Apr 18, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm leaning towards dropping it entirely, at least for legacy Products. We can always infer that using git log. But I think we're planning internal sync with you about the entire PHP API Reference, aiming to discuss that as well.

*
* @param \Ibexa\Contracts\Core\Repository\Values\User\RoleCreateStruct $roleCreateStruct
*
Expand All @@ -44,7 +44,7 @@ public function createRole(RoleCreateStruct $roleCreateStruct): RoleDraft;
/**
* Creates a new RoleDraft for existing Role.
*
* @since 6.0
* @since 1.0 eZ Platform 1.0 (ezpublish-kernel 6.0)
*
* @param \Ibexa\Contracts\Core\Repository\Values\User\Role $role
*
Expand All @@ -59,7 +59,7 @@ public function createRoleDraft(Role $role): RoleDraft;
/**
* Copies an existing Role.
*
* @since eZ Platform 3.0
* @since 3.0 eZ Platform 3.0 (ezplatform-kernel 1.0)
*
* @throws \Ibexa\Contracts\Core\Repository\Exceptions\UnauthorizedException if the authenticated user is not allowed to copy a role
* @throws \Ibexa\Contracts\Core\Repository\Exceptions\InvalidArgumentException if the name of the role already exists or if limitation of the same type
Expand All @@ -73,7 +73,7 @@ public function copyRole(Role $role, RoleCopyStruct $roleCopyStruct): Role;
/**
* Loads a RoleDraft for the given id.
*
* @since 6.0
* @since 1.0 eZ Platform 1.0 (ezpublish-kernel 6.0)
*
* @param int $id
*
Expand All @@ -99,7 +99,7 @@ public function loadRoleDraftByRoleId(int $roleId): RoleDraft;
/**
* Updates the properties of a RoleDraft.
*
* @since 6.0
* @since 1.0 eZ Platform 1.0 (ezpublish-kernel 6.0)
*
* @param \Ibexa\Contracts\Core\Repository\Values\User\RoleDraft $roleDraft
* @param \Ibexa\Contracts\Core\Repository\Values\User\RoleUpdateStruct $roleUpdateStruct
Expand All @@ -114,7 +114,7 @@ public function updateRoleDraft(RoleDraft $roleDraft, RoleUpdateStruct $roleUpda
/**
* Adds a new policy to the RoleDraft.
*
* @since 6.0
* @since 1.0 eZ Platform 1.0 (ezpublish-kernel 6.0)
*
* @param \Ibexa\Contracts\Core\Repository\Values\User\RoleDraft $roleDraft
* @param \Ibexa\Contracts\Core\Repository\Values\User\PolicyCreateStruct $policyCreateStruct
Expand All @@ -131,7 +131,7 @@ public function addPolicyByRoleDraft(RoleDraft $roleDraft, PolicyCreateStruct $p
/**
* Removes a policy from a RoleDraft.
*
* @since 6.0
* @since 1.0 eZ Platform 1.0 (ezpublish-kernel 6.0)
*
* @param \Ibexa\Contracts\Core\Repository\Values\User\RoleDraft $roleDraft
* @param \Ibexa\Contracts\Core\Repository\Values\User\PolicyDraft $policyDraft the policy to remove from the RoleDraft
Expand All @@ -147,7 +147,7 @@ public function removePolicyByRoleDraft(RoleDraft $roleDraft, PolicyDraft $polic
* Updates the limitations of a policy. The module and function cannot be changed and
* the limitations are replaced by the ones in $roleUpdateStruct.
*
* @since 6.0
* @since 1.0 eZ Platform 1.0 (ezpublish-kernel 6.0)
*
* @param \Ibexa\Contracts\Core\Repository\Values\User\RoleDraft $roleDraft
* @param \Ibexa\Contracts\Core\Repository\Values\User\PolicyDraft $policy
Expand All @@ -169,7 +169,7 @@ public function updatePolicyByRoleDraft(
/**
* Deletes the given RoleDraft.
*
* @since 6.0
* @since 1.0 eZ Platform 1.0 (ezpublish-kernel 6.0)
*
* @param \Ibexa\Contracts\Core\Repository\Values\User\RoleDraft $roleDraft
*
Expand All @@ -180,7 +180,7 @@ public function deleteRoleDraft(RoleDraft $roleDraft): void;
/**
* Publishes the given RoleDraft.
*
* @since 6.0
* @since 1.0 eZ Platform 1.0 (ezpublish-kernel 6.0)
*
* @param \Ibexa\Contracts\Core\Repository\Values\User\RoleDraft $roleDraft
*
Expand Down
20 changes: 10 additions & 10 deletions src/contracts/Repository/SearchService.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ interface SearchService
* When this is supported you can expect search engine to populate SearchHit->score and SearchResult->maxScore
* properties as well as sort by this if no sort clauses are specified.
*
* @since 6.12 (constant added in 6.7.6 and up)
* @since 1.12 eZ Platform 1.12 (ezpublish-kernel 6.12) (constant added in 6.7.6 and up)
*/
public const CAPABILITY_SCORING = 1;

Expand All @@ -40,7 +40,7 @@ interface SearchService
* - Some of the faceting features are still work in progress in API and won't be further matured before in 7 .x
* releases
*
* @since 6.12 (constant added in 6.7.6 and up)
* @since 1.12 eZ Platform 1.12 (ezpublish-kernel 6.12) (constant added in 6.7.6 and up)
*/
public const CAPABILITY_FACETS = 2;

Expand All @@ -52,7 +52,7 @@ interface SearchService
* allow you on some search criteria to specify this custom field to rather query on that instead of the default
* field generated by the system.
*
* @since 6.12 (constant added in 6.7.6 and up)
* @since 1.12 eZ Platform 1.12 (ezpublish-kernel 6.12) (constant added in 6.7.6 and up)
*/
public const CAPABILITY_CUSTOM_FIELDS = 4;

Expand All @@ -65,7 +65,7 @@ interface SearchService
* interact with FullText criterion (singular) which is the most relevant here. Also given how FullText can be part of a more complex criteria it
* might imply a need to more strictly define where users are supposed to place FullText vs other criteria.
*
* @since 6.12 (constant added in 6.7.6 and up)
* @since 1.12 eZ Platform 1.12 (ezpublish-kernel 6.12) (constant added in 6.7.6 and up)
*/
public const CAPABILITY_SPELLCHECK = 8;

Expand All @@ -83,7 +83,7 @@ interface SearchService
* was matched and leave it to field type to render result with that info taking into account. But for now it is
* designed as simple string field, so should be string with for instance `<mark>` around matched text.
*
* @since 6.12 (constant added in 6.7.6 and up)
* @since 1.12 eZ Platform 1.12 (ezpublish-kernel 6.12) (constant added in 6.7.6 and up)
*/
public const CAPABILITY_HIGHLIGHT = 16;

Expand All @@ -93,7 +93,7 @@ interface SearchService
* WARNING: This feature is considered experimental given it is not completely clear what it is supposed to do. Feature
* might be deprecated in the future.
*
* @since 6.12 (constant added in 6.7.6 and up)
* @since 1.12 eZ Platform 1.12 (ezpublish-kernel 6.12) (constant added in 6.7.6 and up)
*/
public const CAPABILITY_SUGGEST = 32;

Expand All @@ -102,15 +102,15 @@ interface SearchService
*
* Advance full text is a feature making to possible by current engine to parse advance full text expressions.
*
* @since 6.12 (constant added in 6.7.6 and up)
* @since 1.12 eZ Platform 1.12 (ezpublish-kernel 6.12) (constant added in 6.7.6 and up)
* @see \Ibexa\Contracts\Core\Repository\Values\Content\Query\Criterion\FullText
*/
public const CAPABILITY_ADVANCED_FULLTEXT = 64;

/**
* Capability flag for aggregation feature for use with {@see ::supports()}.
*
* @since eZ Platform 3.2
* @since 3.2 eZ Platform 3.2 (ezplatform-kernel 1.2)
*/
public const CAPABILITY_AGGREGATIONS = 128;

Expand All @@ -137,7 +137,7 @@ public function findContent(Query $query, array $languageFilter = [], bool $filt
* it can be more efficient for use cases where you don't need the full Content. Also including use cases
* where content will be loaded by separate code, like an ESI based sub requests that takes content ID as input.
*
* @since 5.4.5
* @since 0.5.4.5 eZ Publish 5.4 (ezpublish-kernel 5.4)
*
* @throws \Ibexa\Contracts\Core\Repository\Exceptions\InvalidArgumentException if query is not valid
*
Expand Down Expand Up @@ -198,7 +198,7 @@ public function findLocations(LocationQuery $query, array $languageFilter = [],
*
* Will return false if search engine does not implement {@see \Ibexa\Contracts\Core\Search\Capable}.
*
* @since 6.12
* @since 1.12 eZ Platform 1.12 (ezpublish-kernel 6.12)
*
* @param int $capabilityFlag One of CAPABILITY_* constants.
*
Expand Down
48 changes: 31 additions & 17 deletions src/contracts/Repository/Values/Content/Query/Criterion/Operator/Specifications.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,22 +11,22 @@
/**
* This class is used by Criteria to describe which operators they support.
*
* Instances of this class are returned in an array by the {@see Criterion::getSpecifications()} method
* Instances of this class are returned in an array by the Criterion::getSpecifications() method
*
* @see \Ibexa\Contracts\Core\Repository\Values\Content\Query\Criterion::getSpecifications()
*/
class Specifications
{
/**
* Criterion input type description constants.
*/
/** Criterion input type description constants: single. */
public const FORMAT_SINGLE = 1;
/** Criterion input type description constants: array. */
public const FORMAT_ARRAY = 2;

/**
* Criterion input value type description constants.
* Used by {@see getDescription()} to say which type of values an operator expects.
*/
/** Criterion input value type description constants: integer. */
public const TYPE_INTEGER = 1;
/** Criterion input value type description constants: string. */
public const TYPE_STRING = 2;
/** Criterion input value type description constants: boolean. */
public const TYPE_BOOLEAN = 4;

/**
Expand All @@ -35,10 +35,13 @@ class Specifications
public $operator;

/**
* Format supported for the Criterion value, either {@see self::FORMAT_SINGLE} for single
* or {@see self::FORMAT_ARRAY} for multiple.
* Format supported for the Criterion value.
*
* Either {@see Specifications::FORMAT_SINGLE} for single
* or {@see Specifications::FORMAT_ARRAY} for multiple.
*
* @see self::FORMAT_*
* @see Specifications::FORMAT_SINGLE
* @see Specifications::FORMAT_ARRAY
*
* @var int
*/
Expand All @@ -47,7 +50,9 @@ class Specifications
/**
* Accepted values types, specifying what type of variables are accepted as a value.
*
* @see self::TYPE_*
* @see Specifications::TYPE_INTEGER
* @see Specifications::TYPE_STRING
* @see Specifications::TYPE_BOOLEAN
*
* @var int
*/
Expand All @@ -56,20 +61,29 @@ class Specifications
/**
* Limitation on the number of items as the value.
*
* Only usable if {@see $valueFormat} is {@see self::FORMAT_ARRAY}.
* Only usable if {@see Specifications::$valueFormat} is {@see Specifications::FORMAT_ARRAY}.
* Not setting it means that 1...n will be required
*
* @see Specifications::$valueFormat
* @see Specifications::FORMAT_ARRAY
*
* @var int
*/
public $valueCount;

/**
* Creates a new Specifications object.
*
* @param string $operator The specified operator, as one of the Operator::* constants
* @param int $valueFormat The accepted value format, either {@see self::FORMAT_ARRAY} or {@see self::FORMAT_SINGLE}
* @param int $valueTypes The supported value types, as a bit field of the {@see self::TYPE_*} constants
* @param int $valueCount The required number of values, when the accepted format is {@see self::FORMAT_ARRAY}
* @param string $operator The specified operator, as one of the {@see \Ibexa\Contracts\Core\Repository\Values\Content\Query\Criterion\Operator}::* constants
* @param int $valueFormat The accepted value format, either {@see Specifications::FORMAT_ARRAY} or {@see Specifications::FORMAT_SINGLE}
* @param int $valueTypes The supported value types, as a bit field of the self::TYPE_* constants
* @param int $valueCount The required number of values, when the accepted format is {@see Specifications::FORMAT_ARRAY}
*
* @see Specifications::FORMAT_SINGLE
* @see Specifications::FORMAT_ARRAY
* @see Specifications::TYPE_INTEGER
* @see Specifications::TYPE_STRING
* @see Specifications::TYPE_BOOLEAN
*/
public function __construct(string $operator, int $valueFormat, ?int $valueTypes = null, ?int $valueCount = null)
{
Expand Down
6 changes: 5 additions & 1 deletion src/contracts/Repository/Values/Content/Relation.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -89,7 +89,11 @@ abstract public function getDestinationContentInfo(): ContentInfo;
/**
* The relation type bitmask.
*
* @see Relation::COMMON, Relation::EMBED, Relation::LINK, Relation::FIELD, Relation::ASSET
* @see Relation::COMMON
* @see Relation::EMBED
* @see Relation::LINK
* @see Relation::FIELD
* @see Relation::ASSET
*
* @var int
*/
Expand Down
2 changes: 2 additions & 0 deletions src/lib/Pagination/Pagerfanta/SearchResultAdapter.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,8 @@
use Pagerfanta\Adapter\AdapterInterface;

/**
* Contract for SearchService based adapters.
*
* Contract for {@see \Ibexa\Contracts\Core\Repository\SearchService} based adapters.
*/
interface SearchResultAdapter extends AdapterInterface
Expand Down