From 91c8406e27f89449ca36ea49a56ab76d8c75fdf0 Mon Sep 17 00:00:00 2001
From: Manav Rathi <manav@mrmr.io>
Date: Thu, 3 Oct 2024 11:51:58 +0530
Subject: [PATCH] Doc

---
 web/packages/new/photos/utils/file.ts | 29 ++++++++++++++++++---------
 1 file changed, 20 insertions(+), 9 deletions(-)

diff --git a/web/packages/new/photos/utils/file.ts b/web/packages/new/photos/utils/file.ts
index a89d25b3f3..29de3e2853 100644
--- a/web/packages/new/photos/utils/file.ts
+++ b/web/packages/new/photos/utils/file.ts
@@ -27,6 +27,21 @@ export const fileLogID = (enteFile: EnteFile) =>
     `file ${enteFile.metadata.title ?? "-"} (${enteFile.id})`;
 
 /**
+ * Update the in-memory representation of an array of {@link EnteFile} to
+ * reflect user edits since the file was uploaded.
+ *
+ * This is a list variant of {@link mergeMetadata1}.
+ */
+export const mergeMetadata = (files: EnteFile[]) =>
+    files.map((file) => mergeMetadata1(file));
+
+/**
+ * Update the immutable fields of an (in-memory) {@link EnteFile} with any edits
+ * that the user has made to their corresponding mutable metadata fields.
+ *
+ * This function updates a single file, see {@link mergeMetadata} for a
+ * convenience function to run it on an array of files.
+ *
  * [Note: File name for local EnteFile objects]
  *
  * The title property in a file's metadata is the original file's name. The
@@ -38,25 +53,21 @@ export const fileLogID = (enteFile: EnteFile) =>
  * Effectively, post this step, the file's metadata.title can be used in lieu of
  * its filename.
  */
-export function mergeMetadata(files: EnteFile[]): EnteFile[] {
-    return files.map((file) => mergeMetadata1(file));
-}
-
-export function mergeMetadata1(file: EnteFile): EnteFile {
+export const mergeMetadata1 = (file: EnteFile): EnteFile => {
     if (file.pubMagicMetadata?.data.editedTime) {
         file.metadata.creationTime = file.pubMagicMetadata.data.editedTime;
     }
     if (file.pubMagicMetadata?.data.editedName) {
         file.metadata.title = file.pubMagicMetadata.data.editedName;
     }
-    // In a very rare cases (have found only one so far, a very old file
-    // uploaded by an initial dev version of Ente) the photo has no modification
-    // time. Gracefully handle such cases.
+    // In a very rare cases (have found only one so far, a very old file in
+    // Vishnu's account, uploaded by an initial dev version of Ente) the photo
+    // has no modification time. Gracefully handle such cases.
     if (!file.metadata.modificationTime)
         file.metadata.modificationTime = file.metadata.creationTime;
 
     return file;
-}
+};
 
 /**
  * Return a new {@link Blob} containing data in a format that the browser