Enhance PHPDoc

[adriendupuis]

🎫 Issue	IBX-XXXXX

Related PRs:

• ibexa/payment#161
• Enhance PHPDoc rest#142

Description:

• Add missing summaries (discovered during Enhance PHP API REF metadata documentation-developer#2575). A summary is the first line of a docblock. It can't have advanced formatting as it won't be rendered. Fix several not-rendered inline {@see tags
• Type array keys to avoid generic array<string|int, rendering.
• Use triple-backticks to have code blocks instead of <code> rendered as a single line.
• Fix some @see syntax to have a working link.
• Use class name instead of self to have a link (to the current page, debatable, it could also be $this).
• Reword some descriptions.
• ValueObject: Replace @ignore This method is for internal use with the dedicated @internal, fix some @uses tags.

Preview

Preview is build on top of ibexa/documentation-developer#2584.
But the following comparisons focus on the improvements brought by the packages' PRs.

• Ibexa\Contracts\Core\FieldType\FieldType
  • Before has code examples on one line, and with old school array() syntax.
  • After has code examples in blocks with preserved new lines, and with a more modern [] syntax.
• Ibexa\Contracts\Core\FieldType\Generic\Type
  • Before has code examples on one line, checkValueType() makes a not-clickable reference to acceptValue().
  • After has code example blocks with preserved new lines, and checkValueType() a working link to acceptValue().
• Ibexa\Contracts\Core\FieldType\Generic\ValidationError\ConstraintViolationAdapter
  • Before has not rendered @see tags in its introduction and <meta name="description" because the summary line can't have advanced format.
  • After has a simple summary then a short description with @see rendered as links to references.
• Ibexa\Contracts\Core\Limitation\Target\Builder\VersionBuilder
  • Before has not rendered @see tags in its introduction, and some string|int untyped array keys.
  • After has more links, and typed array keys.
• Ibexa\Contracts\Core\Limitation\Type
  • Before has a description for ACCESS_GRANTED which, in fact, is a description for the three ACCESS_ constants (grouped docblock doesn't exist and because of alphabetic order, the description ends after what it introduces), about the same for VALUE_SCHEMA_ constants, a not-rendered @see, and a not typed array key.
  • After has a description for each constants, links, and typed array keys.
• Ibexa\Contracts\Core\Repository\LocationService
  • Before has a not-rendered @see, and untyped array keys.
  • After has a new summary for count(), a working link in its description, typed keys on several arrays.
• Ibexa\Contracts\Core\Repository\SearchService
  • Before has several not-rendered @see.
  • After has a more readable description CAPABILITY_CUSTOM_FIELDS, new summaries, and more links.
• Ibexa\Contracts\Core\Repository\Values\Content\Location
  • Before has some @deprecated not rendered because wrongly nested.
    • Nota bene: This happens in other classes. It's on my todo list for another PR.
  • After has the read-only properties' summaries rewritten. Nota bene: The way a property is declared being both protected and magically publicly read-only (@property-read) creates duplicates: it's declared twice in the PHP code, and documented twice in the reference. This is an issue I'll come back to later.
• Ibexa\Contracts\Core\Repository\Values\Content\Query\Criterion
  • Before, has a not-rendered @see, misses links to properties and constants, and has an example rendered as a single line.
  • After has links and a proper code block.
• Ibexa\Contracts\Core\Repository\Values\Content\Query\Criterion\DateMetadata
  • Before has an example rendered as a single line.
  • After has well rendered example, more readable descriptions, a link from DateMetadata::TRASHED to TrashService::findTrashItems(), and more links in general.
• Ibexa\Contracts\Core\Repository\Values\Content\Query\Criterion\UserMetadata
  • Before has two one-line examples, a typo in a quoted constant, a lack of links.
  • After has code blocks, enhanced descriptions, more links.
• Ibexa\Contracts\Core\Repository\Values\Content\Query\Criterion\Operator\Specifications
  • Before's description quotes Criterion::getSpecifications() without a link.
  • After: description is reworded, a link to Criterion::getSpecifications() is added with an inline tag instead of a separated tag below.
• Ibexa\Contracts\Core\Repository\Values\ValueObject
  • Before quotes the internal ValueObject::attributes(), has not-typed array keys,
  • After has typed array keys.
• Ibexa\Contracts\Core\Search\Capable
  • Before has a not rendered @see in its summary.
  • After has a new summary, the link is in its description, and a link to SearchService helps to see the CAPABILITY_ constants.

For QA:

Documentation:

[adriendupuis]

I didn't find such property in the contracts namespace. (I may haven't look well enough in the namespace.) It might not be in this contracts namespace, and hidden by abstraction. If no link can be made to it, it probably don't worth being mentioned.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud