Updated Libs.Entity classes docs.

Author: arabcoders

src/Libs/Entity/StateEntity.php

@@ -13,24 +13,75 @@ final class StateEntity implements iState
 {
     use LoggerAwareTrait;
 
+    /**
+     * @var array $data Holds the original entity data.
+     */
     private array $data = [];
+    /**
+     * @var bool $tainted Flag indicating if the data is tainted based on its event type.
+     */
     private bool $tainted = false;
 
+    /**
+     * @var string|int|null $id The corresponding database id.
+     */
     public null|string|int $id = null;
+
+    /**
+     * @var string $type What type of data this entity holds.
+     */
     public string $type = '';
+    /**
+     * @var int $updated When was the entity last updated.
+     */
     public int $updated = 0;
+
+    /**
+     * @var int $watched Whether the entity is watched or not.
+     */
     public int $watched = 0;
 
+    /**
+     * @var string $via The backend that this entity data belongs to.
+     */
     public string $via = '';
+
+    /**
+     * @var string $title The title of the entity usually in format of "Movie Title (Year)" if event type is movie. Or "Series Title (Year) - Season x Episode" if event type is episode.
+     */
     public string $title = '';
 
+    /**
+     * @var int|null $year The year of the entity.
+     */
     public int|null $year = null;
+    /**
+     * @var int|null $season The season number of the episode if event type is episode.
+     */
     public int|null $season = null;
+    /**
+     * @var int|null $episode The episode number of the episode event type is episode.
+     */
     public int|null $episode = null;
 
+    /**
+     * @var array $parent The parent guids for this entity. Empty if event type is movie.
+     */
     public array $parent = [];
+
+    /**
+     * @var array $guids The guids for this entity. Empty if event type is episode.
+     */
     public array $guids = [];
+
+    /**
+     * @var array $metadata holds the metadata from various backends.
+     */
     public array $metadata = [];
+
+    /**
+     * @var array $extra holds the extra data from various backends.
+     */
     public array $extra = [];
 
     public function __construct(array $data)
@@ -455,6 +506,17 @@ public function getPlayProgress(): int
         return $lastProgress;
     }
 
+    /**
+     * Checks if the value of a given key in the entity object is equal to the corresponding value in the current object.
+     * Some keys are special and require special logic to compare. For example, the updated and watched keys are special
+     * because they are tied together.
+     *
+     * @param string $key The key to check in the entity object.
+     * @param iState $entity The entity object to compare the key value with.
+     *
+     * @return bool Returns true if the value of the key in the entity object is equal to the value in the current object,
+     *              otherwise returns false.
+     */
     private function isEqualValue(string $key, iState $entity): bool
     {
         if (iState::COLUMN_UPDATED === $key || iState::COLUMN_WATCHED === $key) {
@@ -468,6 +530,17 @@ private function isEqualValue(string $key, iState $entity): bool
         return true;
     }
 
+    /**
+     * Updates the value of a given key in the current object with the corresponding value from the remote object.
+     * The method follows certain logic for specific keys such as "updated" and "watched". For these keys, if the remote
+     * object has a greater "updated" value and a different "watched" value compared to the current object, the values in
+     * the current object are updated with the values from the remote object. If the key is an array column the method uses
+     * the recursive replacement to update the value of the key in the current object with the value from the remote
+     * object. Otherwise, it simply assigns the value of the key from the remote object to the current object.
+     *
+     * @param string $key The key to update in the current object.
+     * @param iState $remote The remote object to get the updated value from.
+     */
     private function updateValue(string $key, iState $remote): void
     {
         if (iState::COLUMN_UPDATED === $key || iState::COLUMN_WATCHED === $key) {
@@ -490,6 +563,16 @@ private function updateValue(string $key, iState $remote): void
         }
     }
 
+    /**
+     * Calculates the difference between two arrays by comparing their values recursively.
+     *
+     * @param array $oldArray The original array to compare.
+     * @param array $newArray The new array to compare.
+     *
+     * @return array Returns an associative array that contains the differences between the two arrays. The keys are the
+     *               differing elements from the new array, and the values are arrays that contain the old and new values
+     *               for each differing element.
+     */
     private function arrayDiff(array $oldArray, array $newArray): array
     {
         $difference = [];