From bed8180f5bda06b901136af703ddd3ec2f66e3b1 Mon Sep 17 00:00:00 2001
From: Dogukan Cavdaroglu <dogukan@srdc.com.tr>
Date: Tue, 22 Oct 2024 10:39:15 +0300
Subject: [PATCH] :memo: docs: Extend the documentation of some models in
 FhirMappingResult class

---
 .../engine/model/FhirMappingResult.scala      | 29 ++++++++++++++++---
 1 file changed, 25 insertions(+), 4 deletions(-)

diff --git a/tofhir-engine/src/main/scala/io/tofhir/engine/model/FhirMappingResult.scala b/tofhir-engine/src/main/scala/io/tofhir/engine/model/FhirMappingResult.scala
index 730b6dc1..eb66a322 100644
--- a/tofhir-engine/src/main/scala/io/tofhir/engine/model/FhirMappingResult.scala
+++ b/tofhir-engine/src/main/scala/io/tofhir/engine/model/FhirMappingResult.scala
@@ -26,7 +26,21 @@ trait BaseFhirMappingResult {
   val timestamp: Timestamp
 
   /**
-   * If there is a problem in the process, the JSON serialization of the source data
+   * A JSON serialization of the source data. The main data source is represented with the "mainSource" key,
+   * while other data sources are serialized using their respective source aliases as keys.
+   *
+   * Example structure:
+   * {
+   *  "mainSource": {
+   *    ... // Serialized data from the main source
+   *  },
+   *  "encounters": {
+   *    ... // Data from encounters source
+   *  },
+   *  "observations": {
+   *    ... // Data from observations source
+   *  }
+   * }
    */
   val source: String
 
@@ -49,6 +63,13 @@ trait BaseFhirMappingResult {
 /**
  * Case class representing the result of a FHIR mapping process, extending the base mapping result.
  * This model is designed to store the outcome of the mapping, including the generated FHIR resource.
+ *
+ * Each instance of `FhirMappingResult` corresponds to a single FHIR resource, regardless
+ * of how many FHIR resources are created from each input row.
+ *
+ * If the mapping is 1-to-many, multiple instances of `FhirMappingResult` will be created from a single source row,
+ * each holding one of the generated FHIR resources.
+ *
  * It includes the common fields from [[BaseFhirMappingResult]], along with specific information about
  * the FHIR resource type and the serialized output of the mapped resource.
  *
@@ -111,9 +132,9 @@ case class FhirMappingResult(
 }
 
 /**
- * Stores the results of mapping i.e. generated FHIR resources for a source input.
- * It groups the mapped FHIR resources generated from the input data, allowing for easy access to
- * the output for a specific input row.
+ * Represents the result of the mapping process for a single source row, storing the generated FHIR resources.
+ * Each source row corresponds to one instance of `FhirMappingResultsForInput`. If the mapping process is
+ * 1-to-many, the `mappedFhirResources` field contains all the FHIR resources created from the single source row.
  *
  * In addition to the common fields from [[BaseFhirMappingResult]], it includes a collection of mapped
  * FHIR resources, which represent the outcome of the mapping process for each input source.