From 73496e0e1f2ed3f1b53d0af466407e5fd011d810 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Julien=20Fastr=C3=A9?= <julien.fastre@champs-libres.coop>
Date: Wed, 23 Apr 2025 09:46:11 +0200
Subject: [PATCH] Add documentation for trait ExportDataNormalizerTrait

---
 .../Export/ExportDataNormalizerTrait.php      | 40 ++++++++++++++++++-
 1 file changed, 39 insertions(+), 1 deletion(-)

diff --git a/src/Bundle/ChillMainBundle/Export/ExportDataNormalizerTrait.php b/src/Bundle/ChillMainBundle/Export/ExportDataNormalizerTrait.php
index 16c252e4e..3ff902795 100644
--- a/src/Bundle/ChillMainBundle/Export/ExportDataNormalizerTrait.php
+++ b/src/Bundle/ChillMainBundle/Export/ExportDataNormalizerTrait.php
@@ -14,10 +14,19 @@ namespace Chill\MainBundle\Export;
 use Doctrine\Common\Collections\Collection;
 use Doctrine\Persistence\ObjectRepository;
 
+/**
+ * Provides utilities for normalizing and denormalizing data entities and dates.
+ */
 trait ExportDataNormalizerTrait
 {
     /**
-     * @param object|list<object> $entity
+     * Normalizes a Doctrine entity or a collection of entities to extract their identifiers.
+     *
+     * @param object|list<object>|null $entity the entity or collection of entities to normalize
+     *
+     * @return array|int|string Returns the identifier(s) of the entity or entities. If an array of entities is provided,
+     *                          an array of their identifiers is returned. If a single entity is provided, its identifier
+     *                          is returned. If null, returns an empty value.
      */
     public function normalizeDoctrineEntity(object|array|null $entity): array|int|string
     {
@@ -31,6 +40,16 @@ trait ExportDataNormalizerTrait
         return $entity?->getId();
     }
 
+    /**
+     * Denormalizes a Doctrine entity by fetching it from the provided repository based on the given ID(s).
+     *
+     * @param list<int>|int|string $id         the identifier(s) of the entity to find
+     * @param ObjectRepository     $repository the Doctrine repository to query
+     *
+     * @return object|array<object> the found entity or an array of entities if multiple IDs are provided
+     *
+     * @throws \UnexpectedValueException when the entity with the given ID does not exist
+     */
     public function denormalizeDoctrineEntity(array|int|string $id, ObjectRepository $repository): object|array
     {
         if (is_array($id)) {
@@ -44,6 +63,13 @@ trait ExportDataNormalizerTrait
         return $object;
     }
 
+    /**
+     * Normalizes a provided date into a specific string format.
+     *
+     * @param \DateTimeImmutable|\DateTime $date the date instance to normalize
+     *
+     * @return string a formatted string containing the type and formatted date
+     */
     public function normalizeDate(\DateTimeImmutable|\DateTime $date): string
     {
         return sprintf(
@@ -53,6 +79,18 @@ trait ExportDataNormalizerTrait
         );
     }
 
+    /**
+     * Denormalizes a string back into a DateTime instance.
+     *
+     * The string is expected to contain a kind selector (e.g., 'imm1' or 'mut1')
+     * to determine the type of DateTime object (immutable or mutable) followed by a date format.
+     *
+     * @param string $date the string to be denormalized, containing the kind selector and formatted date
+     *
+     * @return \DateTimeImmutable|\DateTime a DateTime instance created from the given string
+     *
+     * @throws \UnexpectedValueException if the kind selector or date format is invalid
+     */
     public function denormalizeDate(string $date): \DateTimeImmutable|\DateTime
     {
         $format = 'd-m-Y-H:i:s.u e';