Enhanced contracts 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.
• Type array values
  • It fixes several "no value type specified in iterable type array" so PHPStan file is updated.
• 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 (except for ValueObject::valueSchema()).
• 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:

[adamwojs]

@adriendupuis Rebase is needed here

[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