Merge pull request #1478 from internxt/coderabbitai/docstrings/d5f671c

📝 Add docstrings to `fix/modification-time-for-file-and-folders`

Author: AlexisMora

src/backend/features/remote-sync/file-explorer/check-if-modified.ts

@@ -13,6 +13,14 @@ type Props = {
   isFirstExecution: boolean;
 };
 
+/**
+ * Synchronizes a local file with its remote Drive counterpart when their recorded sizes differ.
+ *
+ * On the first execution, local changes are uploaded when the file is fully hydrated. Remote changes
+ * update the local placeholder and pin state.
+ *
+ * @param isFirstExecution - Whether this is the initial synchronization check for the file.
+ */
 export async function checkIfModified({ ctx, remote, local, isFirstExecution }: Props) {
   const path = remote.absolutePath;
 

src/backend/features/remote-sync/file-explorer/update-file-placeholder.ts

@@ -14,6 +14,13 @@ type Props = {
   isFirstExecution: boolean;
 };
 
+/**
+ * Synchronizes a local Windows file placeholder with its remote file metadata and state.
+ *
+ * @param remote - The remote file to synchronize.
+ * @param files - Local files indexed by remote UUID.
+ * @param isFirstExecution - Whether this is the first synchronization after startup.
+ */
 export async function updateFilePlaceholder({ ctx, remote, files, isFirstExecution }: Props) {
   const path = remote.absolutePath;
   const { size } = remote;

src/backend/features/remote-sync/file-explorer/update-folder-placeholder.ts

@@ -11,6 +11,13 @@ type Props = {
   folders: FileExplorerFolders;
 };
 
+/**
+ * Updates the local placeholder for a remote folder.
+ *
+ * @param remote - The remote folder whose placeholder should be updated
+ * @param folders - The local folders indexed by remote UUID
+ * @returns `true` if the placeholder is created or updated, `false` if the remote name is invalid or an error occurs
+ */
 export async function updateFolderPlaceholder({ ctx, remote, folders }: Props) {
   const path = remote.absolutePath;
 

src/backend/features/sync/actions/services/create-folder.ts

@@ -12,6 +12,13 @@ type Props = {
   parentUuid: FolderUuid;
 };
 
+/**
+ * Creates a remote folder for a local path and records its synchronization state.
+ *
+ * @param path - The local folder path to create remotely
+ * @param parentUuid - The UUID of the remote parent folder
+ * @returns The result of persisting the created or existing folder, or `undefined` when the operation is aborted or fails
+ */
 export async function createFolder({ ctx, path, parentUuid }: Props) {
   const name = basename(path);
   const { birthtime, mtime } = await FileSystemModule.statThrow({ absolutePath: path });

src/infra/sqlite/services/file/create-or-update-batch.ts

@@ -10,6 +10,12 @@ type Props = {
   files: DriveFile[];
 };
 
+/**
+ * Creates or updates file records in the database in batches.
+ *
+ * @param files - The file records to create or update
+ * @returns A `SqliteError` if the operation fails; otherwise, `undefined`.
+ */
 export async function createOrUpdateBatch({ files }: Props) {
   if (files.length === 0) return;
 

src/infra/sqlite/services/file/create-or-update.ts

@@ -8,6 +8,12 @@ type Props = {
   file: DriveFile;
 };
 
+/**
+ * Creates or updates a stored file record.
+ *
+ * @param file - The file record to persist
+ * @returns The parsed file data, or `undefined` if persistence or parsing fails
+ */
 export function createOrUpdate({ file }: Props) {
   try {
     db.prepare(upsertQuery).run({

src/infra/sqlite/services/file/parse-data.ts

@@ -5,6 +5,12 @@ type TProps = {
   data: DriveFile;
 };
 
+/**
+ * Converts drive file data into a normalized simple drive file.
+ *
+ * @param data - The source drive file data
+ * @returns The normalized drive file
+ */
 export function parseData({ data }: TProps): SimpleDriveFile {
   let name = data.plainName;
   if (data.type) name += `.${data.type}`;

src/infra/sqlite/services/folder/create-or-update-batch.ts

@@ -10,6 +10,12 @@ type Props = {
   folders: DriveFolder[];
 };
 
+/**
+ * Creates or updates folder records in the database in batches.
+ *
+ * @param folders - The folder records to create or update
+ * @returns `undefined` when processing succeeds, or a `SqliteError` when processing fails
+ */
 export async function createOrUpdateBatch({ folders }: Props) {
   if (folders.length === 0) return;
 

src/infra/sqlite/services/folder/create-or-update.ts

@@ -8,6 +8,12 @@ type Props = {
   folder: DriveFolder;
 };
 
+/**
+ * Creates or updates a folder record and returns its parsed representation.
+ *
+ * @param folder - The folder to persist.
+ * @returns The parsed folder, or `undefined` if persistence or parsing fails.
+ */
 export function createOrUpdate({ folder }: Props) {
   try {
     db.prepare(upsertQuery).run({

src/infra/sqlite/services/folder/parse-data.ts

@@ -5,6 +5,12 @@ type TProps = {
   data: DriveFolder;
 };
 
+/**
+ * Converts drive folder data into a simplified folder representation.
+ *
+ * @param data - The drive folder data to convert
+ * @returns A simplified drive folder containing its identifiers, metadata, timestamps, and status
+ */
 export function parseData({ data }: TProps): SimpleDriveFolder {
   return {
     uuid: data.uuid as FolderUuid,