feat: add doc

publicodes · May 15, 2024 · 0d78002 · 0d78002
1 parent 2b664d4
commit 0d78002
Show file tree

Hide file tree

Showing 7 changed files with 79 additions and 1 deletion.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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 }