From ee31d5a0f8b09affc9f6bca4531e867ebee7d67b Mon Sep 17 00:00:00 2001
From: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com>
Date: Mon, 16 Dec 2024 17:37:49 +0100
Subject: [PATCH] Enhance `ValueObject` phpdoc

- Describes a bit more `getProperties`
- Details `getProperties` param type and returned type
- Hides link to internal function
- Uses `@internal` as a short for "@ignore This method is for internal use"
- Fixes internal links
---
 .../Repository/Values/ValueObject.php         | 38 ++++++++++---------
 1 file changed, 20 insertions(+), 18 deletions(-)

diff --git a/src/contracts/Repository/Values/ValueObject.php b/src/contracts/Repository/Values/ValueObject.php
index 3aa5b81e76..87741261c0 100644
--- a/src/contracts/Repository/Values/ValueObject.php
+++ b/src/contracts/Repository/Values/ValueObject.php
@@ -25,7 +25,7 @@ abstract class ValueObject
      * Readonly properties values must be set using $properties as they are not writable anymore
      * after object has been created.
      *
-     * @param array $properties
+     * @param array<string, mixed> $properties
      */
     public function __construct(array $properties = [])
     {
@@ -35,17 +35,18 @@ public function __construct(array $properties = [])
     }
 
     /**
-     * Function where list of properties are returned.
+     * Returns list of available properties' names.
      *
-     * Used by {@see attributes()}, override to add dynamic properties
+     * {@internal Used by {@see ValueObject::attributes()}}
+     * Override to add dynamic properties.
      *
-     * @uses ::__isset()
+     * @uses ValueObject::__isset()
      *
      * @todo Make object traversable and reuse this function there (hence why this is not exposed)
      *
-     * @param array $dynamicProperties Additional dynamic properties exposed on the object
+     * @param array<int, string> $dynamicProperties Additional dynamic properties exposed on the object
      *
-     * @return array
+     * @return array<int, string>
      */
     protected function getProperties($dynamicProperties = [])
     {
@@ -62,7 +63,7 @@ protected function getProperties($dynamicProperties = [])
     /**
      * Magic set function handling writes to non public properties.
      *
-     * @ignore This method is for internal use
+     * @internal
      *
      * @throws \Ibexa\Contracts\Core\Repository\Exceptions\PropertyNotFoundException When property does not exist
      * @throws \Ibexa\Contracts\Core\Repository\Exceptions\PropertyReadOnlyException When property is readonly (protected)
@@ -83,7 +84,7 @@ public function __set($property, $value)
      *
      * Returns value for all readonly (protected) properties.
      *
-     * @ignore This method is for internal use
+     * @internal
      *
      * @throws \Ibexa\Contracts\Core\Repository\Exceptions\PropertyNotFoundException exception on all reads to undefined properties so typos are not silently accepted.
      *
@@ -104,7 +105,7 @@ public function __get($property)
      *
      * Returns true for all (public/)protected/private properties.
      *
-     * @ignore This method is for internal use
+     * @internal
      *
      * @param string $property Name of the property
      *
@@ -118,12 +119,12 @@ public function __isset($property)
     /**
      * Magic unset function handling unset() to non public properties.
      *
-     * @ignore This method is for internal use
+     * @internal
      *
      * @throws \Ibexa\Contracts\Core\Repository\Exceptions\PropertyNotFoundException exception on all writes to undefined properties so typos are not silently accepted and
      * @throws \Ibexa\Contracts\Core\Repository\Exceptions\PropertyReadOnlyException exception on readonly (protected) properties.
      *
-     * @uses ::__set()
+     * @uses ValueObject::__set()
      *
      * @param string $property Name of the property
      *
@@ -144,7 +145,7 @@ public function __unset($property)
      * var_export() generates code, that calls this method when it
      * is parsed with PHP.
      *
-     * @ignore This method is for internal use
+     * @internal
      *
      * @param mixed[] $array
      *
@@ -158,11 +159,11 @@ public static function __set_state(array $array)
     /**
      * Internal function for Legacy template engine compatibility to get property value.
      *
-     * @ignore This method is for internal use
+     * @internal
      *
      * @deprecated Since 5.0, available purely for legacy eZTemplate compatibility
      *
-     * @uses ::__get()
+     * @uses ValueObject::__get()
      *
      * @param string $property
      *
@@ -176,11 +177,12 @@ final public function attribute($property)
     /**
      * Internal function for Legacy template engine compatibility to get properties.
      *
-     * @ignore This method is for internal use
+     * @internal
      *
      * @deprecated Since 5.0, available purely for legacy eZTemplate compatibility
      *
-     * @uses ::__isset()
+     * @uses ValueObject::getProperties()
+     * @uses ValueObject::__isset()
      *
      * @return array
      */
@@ -192,11 +194,11 @@ final public function attributes()
     /**
      * Internal function for Legacy template engine compatibility to check existence of property.
      *
-     * @ignore This method is for internal use
+     * @internal
      *
      * @deprecated Since 5.0, available purely for legacy eZTemplate compatibility
      *
-     * @uses ::__isset()
+     * @uses ValueObject::__isset()
      *
      * @param string $property
      *