From 0d78002f289b3706abbae9a1e94a7a1535f35f1b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Cl=C3=A9ment?= <clem.auger@hotmail.fr>
Date: Wed, 15 May 2024 17:34:11 +0200
Subject: [PATCH] feat: add doc

---
 source/migration/index.ts                     | 12 +++++++++++
 source/migration/migrateSituation.ts          |  4 +++-
 .../deleteKeyFromSituationAndFoldedSteps.ts   |  6 ++++++
 .../migrateSituation/getValueWithoutQuotes.ts |  6 ++++++
 .../handleSituationKeysMigration.ts           | 21 +++++++++++++++++++
 .../handleSituationValuesMigration.ts         | 18 ++++++++++++++++
 .../migrateSituation/handleSpecialCases.ts    | 13 ++++++++++++
 7 files changed, 79 insertions(+), 1 deletion(-)

diff --git a/source/migration/index.ts b/source/migration/index.ts
index e4eb151..a86cb47 100644
--- a/source/migration/index.ts
+++ b/source/migration/index.ts
@@ -1 +1,13 @@
+/** @packageDocumentation
+
+## Migrate a situation
+
+{@link migrateSituation | `migrateSituation`} allows to migrate situation and foldedSteps based on migration instructions. It's useful in forms when a model is updated and we want old answers to be kept and taken into account in the new model.
+
+### Usage
+
+TODO: add simple example
+
+*/
+
 export * from './migrateSituation'
diff --git a/source/migration/migrateSituation.ts b/source/migration/migrateSituation.ts
index 4d487a7..6e02637 100644
--- a/source/migration/migrateSituation.ts
+++ b/source/migration/migrateSituation.ts
@@ -17,6 +17,7 @@ type Props = {
  * @param foldedSteps - In case of form app, an array containing answered questions.
  * @param migrationInstructions - An object containing keys and values to migrate formatted as follows:
  * @example
+ * ```
  * {
   keysToMigrate: {
     oldKey: newKey
@@ -26,7 +27,8 @@ type Props = {
       oldValue: newValue
   }
   }
- * An example can be found in [nosgestesclimat repository](https://github.com/incubateur-ademe/nosgestesclimat/blob/preprod/migration/migration.yaml).
+  ```
+ * An example can be found in {@link https://github.com/incubateur-ademe/nosgestesclimat/blob/preprod/migration/migration.yaml | nosgestesclimat repository}.
  * @returns The migrated situation (and foldedSteps if specified)
  */
 export function migrateSituation({
diff --git a/source/migration/migrateSituation/deleteKeyFromSituationAndFoldedSteps.ts b/source/migration/migrateSituation/deleteKeyFromSituationAndFoldedSteps.ts
index 3693ba5..2f2bc4d 100644
--- a/source/migration/migrateSituation/deleteKeyFromSituationAndFoldedSteps.ts
+++ b/source/migration/migrateSituation/deleteKeyFromSituationAndFoldedSteps.ts
@@ -1,5 +1,11 @@
 import { DottedName, Situation } from '../../../types/types'
 
+/**
+ * Delete a key from the situation and from the foldedSteps if it exists.
+ * @param ruleName - The rulename to delete.
+ * @param situation - The situation object.
+ * @param foldedSteps - The foldedSteps array.
+ */
 export function deleteKeyFromSituationAndFoldedSteps({
   ruleName,
   situation,
diff --git a/source/migration/migrateSituation/getValueWithoutQuotes.ts b/source/migration/migrateSituation/getValueWithoutQuotes.ts
index daf2758..28413be 100644
--- a/source/migration/migrateSituation/getValueWithoutQuotes.ts
+++ b/source/migration/migrateSituation/getValueWithoutQuotes.ts
@@ -1,5 +1,11 @@
 import { NodeValue } from '../../../types/types'
 
+/**
+ * Returns the value without quotes if it is a string.
+ * @param value - The value to parse.
+ *
+ * @returns The value without quotes if it is a string, null otherwise.
+ */
 export function getValueWithoutQuotes(value: NodeValue) {
   if (
     typeof value !== 'string' ||
diff --git a/source/migration/migrateSituation/handleSituationKeysMigration.ts b/source/migration/migrateSituation/handleSituationKeysMigration.ts
index 217f01f..d6a0569 100644
--- a/source/migration/migrateSituation/handleSituationKeysMigration.ts
+++ b/source/migration/migrateSituation/handleSituationKeysMigration.ts
@@ -14,6 +14,14 @@ type Props = {
   migrationInstructions: MigrationType
 }
 
+/**
+ * Updates a key in the situation object and foldedSteps.
+ * @param ruleName - The name of the rule to update.
+ * @param nodeValue - The new value for the rule.
+ * @param situation - The situation object.
+ * @param foldedSteps - The array of foldedSteps.
+ * @param migrationInstructions - The migration instructions.
+ */
 function updateKeyInSituationAndFoldedSteps({
   ruleName,
   nodeValue,
@@ -39,6 +47,19 @@ function updateKeyInSituationAndFoldedSteps({
   }
 }
 
+/**
+ * Updates a key in the situation and foldedSteps based on migration instructions.
+ * If the key is not a key to migrate but a key to delete, it will be removed from the situation and foldedSteps.
+ * If the key is renamed and needs to be migrated, it will be updated in the situation and foldedSteps.
+ *
+ * @param ruleName - The name of the rule/key to update.
+ * @param nodeValue - The new value for the rule/key.
+ * @param situation - The current situation object.
+ * @param foldedSteps - The current foldedSteps array.
+ * @param migrationInstructions - The migration instructions object.
+ *
+ * @returns An object containing the migrated situation and foldedSteps.
+ */
 export function handleSituationKeysMigration({
   ruleName,
   nodeValue,
diff --git a/source/migration/migrateSituation/handleSituationValuesMigration.ts b/source/migration/migrateSituation/handleSituationValuesMigration.ts
index f834fc4..ecc5b55 100644
--- a/source/migration/migrateSituation/handleSituationValuesMigration.ts
+++ b/source/migration/migrateSituation/handleSituationValuesMigration.ts
@@ -14,6 +14,13 @@ type Props = {
   migrationInstructions: MigrationType
 }
 
+/**
+ * Get the migrated value.
+ *
+ * @param ruleName - The name of the rule to update.
+ * @param nodeValue - The new value for the rule.
+ * @param migrationInstructions - The migration instructions.
+ */
 function getMigratedValue({
   ruleName,
   nodeValue,
@@ -54,6 +61,17 @@ function getMigratedValue({
   ] as string | number
 }
 
+/**
+ * Handles the migration of situation values based on the provided migration instructions.
+ *
+ * @param ruleName - The name of the rule/key to update.
+ * @param nodeValue - The new value for the rule/key.
+ * @param situation - The current situation object.
+ * @param foldedSteps - The current foldedSteps array.
+ * @param migrationInstructions - The migration instructions object.
+ *
+ * @returns An object containing the migrated situation and foldedSteps.
+ */
 export function handleSituationValuesMigration({
   ruleName,
   nodeValue,
diff --git a/source/migration/migrateSituation/handleSpecialCases.ts b/source/migration/migrateSituation/handleSpecialCases.ts
index e4e8032..12c4a29 100644
--- a/source/migration/migrateSituation/handleSpecialCases.ts
+++ b/source/migration/migrateSituation/handleSpecialCases.ts
@@ -5,6 +5,19 @@ type Props = {
 }
 
 // Handle migration of old value format : an object { valeur: number, unité: string }
+/**
+ * Handles special cases during the migration of old value formats.
+ *
+ * @example
+ * ````
+{ valeur: number, unité: string }
+```
+ *
+ * @param ruleName - The name of the rule.
+ * @param nodeValue - The node value.
+ * @param situation - The situation object.
+ * @returns - The updated situation object.
+ */
 export function handleSpecialCases({ ruleName, nodeValue, situation }: Props) {
   const situationUpdated = { ...situation }