chore: update comments

Author: damlayildiz

CLAUDE.md

@@ -55,3 +55,54 @@ For multi-step tasks, state a brief plan:
 ```
 
 Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+
+## 5. Comment Style
+
+**Consistent, purposeful comments. Not noise.**
+
+### JSDoc for public APIs
+Every exported function, interface, and type gets JSDoc documentation:
+```typescript
+/**
+ * Brief description of what it does
+ *
+ * @param foo - Description of parameter
+ * @returns Description of return value
+ */
+export function myFunction(foo: string): number { ... }
+```
+
+### Section markers inside functions
+Use `/** SECTION NAME */` to mark logical sections within complex functions:
+```typescript
+function complexFunction() {
+  /** PARSE OPTIONS */
+  const { foo, bar } = options;
+
+  /** VALIDATE INPUT */
+  if (!foo) throw new Error('foo required');
+
+  /** EXECUTE MAIN LOGIC */
+  const result = doSomething(foo, bar);
+
+  /** CLEANUP */
+  return result;
+}
+```
+
+Common section names: `STATE`, `REFS`, `GUARDS`, `HELPERS`, `CLEANUP`, `EFFECT 1: ...`, `HANDLE ERROR`
+
+### Inline explanations
+Use `// comment` for explaining specific logic:
+```typescript
+// Only sync if auto-sync is not explicitly disabled
+const shouldAutoSync = options?.autoSync !== false;
+
+// On Android, the native call blocks for ~10-15s if offline
+if (Platform.OS === 'android') { ... }
+```
+
+### What NOT to comment
+- Obvious code (`// increment counter` before `count++`)
+- Code that's already clear from good naming
+- Every single line - only where it adds value

src/core/background/backgroundSyncConfig.ts

@@ -14,7 +14,7 @@ export interface BackgroundSyncConfig {
   debug?: boolean;
 }
 
-// Storage key for persisted config
+/** STORAGE KEY */
 const CONFIG_STORAGE_KEY = 'sqlite_sync_background_config';
 
 /**
@@ -44,13 +44,15 @@ export async function persistConfig(
 ): Promise<void> {
   const logger = createLogger(config.debug ?? false);
 
+  /** GUARD: SECURE STORE REQUIRED */
   if (!ExpoSecureStore) {
     logger.warn(
       '⚠️ expo-secure-store not found. Background/terminated sync will not work.'
     );
     return;
   }
 
+  /** SAVE CONFIG */
   try {
     const configJson = JSON.stringify(config);
     await ExpoSecureStore.setItemAsync(CONFIG_STORAGE_KEY, configJson);

src/core/background/backgroundSyncRegistry.ts

@@ -19,17 +19,19 @@ export async function registerBackgroundSync(
 ): Promise<void> {
   const logger = createLogger(config.debug ?? false);
 
+  /** GUARD: DEPENDENCIES REQUIRED */
   if (!isBackgroundSyncAvailable()) {
     logger.warn(
       '⚠️ Background sync dependencies not available (expo-notifications, expo-task-manager, expo-secure-store)'
     );
     return;
   }
 
-  // Persist config for background/terminated task execution
+  /** PERSIST CONFIG */
+  // Config is needed for background/terminated task execution
   await persistConfig(config);
 
-  // Register the task to handle background notifications
+  /** REGISTER TASK */
   await ExpoNotifications.registerTaskAsync(BACKGROUND_SYNC_TASK_NAME);
   logger.info('📲 Background sync task registered');
 }

src/core/background/executeBackgroundSync.ts

@@ -21,11 +21,11 @@ export async function executeBackgroundSync(
   try {
     logger.info('📲 Starting background sync...');
 
-    // Open database connection
+    /** OPEN DATABASE */
     db = await createDatabase(config.databaseName, 'write');
     logger.info('✅ Database connection opened');
 
-    // Initialize sync extension
+    /** INITIALIZE SYNC EXTENSION */
     await initializeSyncExtension(
       db,
       {
@@ -37,7 +37,7 @@ export async function executeBackgroundSync(
       logger
     );
 
-    // Set up updateHook to capture changes during sync
+    /** REGISTER UPDATE HOOK */
     const callback = getBackgroundSyncCallback();
     if (callback) {
       db.updateHook(({ operation, table, rowId }) => {
@@ -50,6 +50,7 @@ export async function executeBackgroundSync(
       logger.info('📲 Update hook registered for change tracking');
     }
 
+    /** EXECUTE SYNC */
     await executeSync(db, logger, {
       useNativeRetry: true,
       maxAttempts: 3,
@@ -58,7 +59,7 @@ export async function executeBackgroundSync(
 
     logger.info('✅ Background sync completed successfully');
 
-    // Call the callback with changes (before closing db so callback can query)
+    /** INVOKE USER CALLBACK */
     if (callback && db) {
       logger.info(
         `📲 Calling background sync callback with ${changes.length} changes`
@@ -76,10 +77,9 @@ export async function executeBackgroundSync(
     logger.error('❌ Background sync failed:', error);
     throw error;
   } finally {
-    // Always close database connection
+    /** CLEANUP */
     if (db) {
       try {
-        // Ensure hook is removed
         db.updateHook(null);
         db.close();
         logger.info('✅ Database connection closed');

src/core/common/logger.ts

@@ -3,10 +3,18 @@
  * Only logs when debug mode is enabled, except for errors which always log
  */
 
+/** CONSTANTS */
 const PREFIX = '[SQLiteSync]';
 
+/** HELPERS */
 const getTimestamp = () => new Date().toISOString();
 
+/**
+ * Create a logger instance with debug mode control
+ *
+ * @param debug - Enable debug logging (info/warn messages)
+ * @returns Logger instance with info, warn, and error methods
+ */
 export const createLogger = (debug: boolean = false) => ({
   /**
    * Log informational messages (only in debug mode)
@@ -34,4 +42,5 @@ export const createLogger = (debug: boolean = false) => ({
   },
 });
 
+/** TYPE EXPORT */
 export type Logger = ReturnType<typeof createLogger>;

src/core/common/optionalDependencies.ts

@@ -3,50 +3,50 @@
  * Loaded once at module initialization
  */
 
-// Module references
+/** MODULE REFERENCES */
 export let ExpoNotifications: any = null;
 export let ExpoTaskManager: any = null;
 export let ExpoSecureStore: any = null;
 export let ExpoConstants: any = null;
+export let ExpoApplication: any = null;
 
-// Load expo-notifications
+/** LOAD EXPO-NOTIFICATIONS */
 try {
   ExpoNotifications = require('expo-notifications');
 } catch {
   // Not available
 }
 
-// Load expo-task-manager
+/** LOAD EXPO-TASK-MANAGER */
 try {
   ExpoTaskManager = require('expo-task-manager');
 } catch {
   // Not available
 }
 
-// Load expo-secure-store
+/** LOAD EXPO-SECURE-STORE */
 try {
   ExpoSecureStore = require('expo-secure-store');
 } catch {
   // Not available
 }
 
-// Load expo-constants
+/** LOAD EXPO-CONSTANTS */
 try {
   const constantsModule = require('expo-constants');
   ExpoConstants = constantsModule.default || constantsModule;
 } catch {
   // Not available
 }
 
-// Load expo-application
-export let ExpoApplication: any = null;
+/** LOAD EXPO-APPLICATION */
 try {
   ExpoApplication = require('expo-application');
 } catch {
   // Not available
 }
 
-// Compound availability check
+/** COMPOUND AVAILABILITY CHECK */
 export const isBackgroundSyncAvailable = () =>
   ExpoNotifications !== null &&
   ExpoTaskManager !== null &&

src/core/database/createDatabase.ts

@@ -17,17 +17,18 @@ export async function createDatabase(
   name: string,
   mode: 'write' | 'read'
 ): Promise<DB> {
+  /** OPEN DATABASE */
   const db = open({ name });
 
-  // Configure WAL mode for both connections
+  /** CONFIGURE WAL MODE */
+  // WAL mode enables concurrent reads and writes
   await db.execute('PRAGMA journal_mode = WAL');
 
+  /** CONFIGURE CONNECTION MODE */
   if (mode === 'write') {
-    // Write connection configuration
     await db.execute('PRAGMA synchronous = NORMAL');
     await db.execute('PRAGMA locking_mode = NORMAL');
   } else {
-    // Read connection configuration
     await db.execute('PRAGMA query_only = true');
   }
 

src/core/polling/calculateAdaptiveSyncInterval.ts

@@ -63,21 +63,21 @@ export function calculateAdaptiveSyncInterval(
     errorBackoffMultiplier,
   } = config;
 
-  // Priority 1: Error backoff (exponential)
+  /** PRIORITY 1: ERROR BACKOFF */
   if (errors > 0) {
     const errorInterval =
       baseInterval * Math.pow(errorBackoffMultiplier, errors);
     return Math.min(errorInterval, maxInterval);
   }
 
-  // Priority 2: Idle backoff (exponential)
+  /** PRIORITY 2: IDLE BACKOFF */
   if (emptySyncs >= emptyThreshold) {
     const backoffPower = emptySyncs - emptyThreshold + 1;
     const idleInterval =
       baseInterval * Math.pow(idleBackoffMultiplier, backoffPower);
     return Math.min(idleInterval, maxInterval);
   }
 
-  // Default: base interval
+  /** DEFAULT: BASE INTERVAL */
   return baseInterval;
 }

src/core/polling/useAdaptivePollingSync.ts

@@ -65,13 +65,12 @@ export function useAdaptivePollingSync(params: AdaptivePollingParams): void {
     syncMode,
   } = params;
 
-  /** REFS */
   const syncTimerRef = useRef<NodeJS.Timeout | null>(null);
   const isPollingActiveRef = useRef<boolean>(false);
 
-  /** ADAPTIVE SYNC POLLING - Dynamic interval with foreground/background awareness */
+  /** ADAPTIVE SYNC POLLING EFFECT */
   useEffect(() => {
-    // Only enable polling when syncMode is 'polling'
+    /** GUARD: POLLING MODE ONLY */
     if (
       !isSyncReady ||
       syncMode !== 'polling' ||
@@ -81,7 +80,7 @@ export function useAdaptivePollingSync(params: AdaptivePollingParams): void {
       return;
     }
 
-    // Pause polling if app is in background
+    /** GUARD: PAUSE WHEN BACKGROUNDED */
     if (appState !== 'active') {
       if (syncTimerRef.current !== null) {
         clearTimeout(syncTimerRef.current);
@@ -91,14 +90,14 @@ export function useAdaptivePollingSync(params: AdaptivePollingParams): void {
       return;
     }
 
-    // Prevent multiple polling loops from starting
+    /** GUARD: PREVENT MULTIPLE LOOPS */
     if (isPollingActiveRef.current) {
       return;
     }
 
     isPollingActiveRef.current = true;
 
-    // Schedule next sync with recursive setTimeout
+    /** RECURSIVE POLLING LOOP */
     const scheduleNextSync = () => {
       if (syncTimerRef.current !== null) {
         clearTimeout(syncTimerRef.current);
@@ -123,6 +122,7 @@ export function useAdaptivePollingSync(params: AdaptivePollingParams): void {
 
     scheduleNextSync();
 
+    /** CLEANUP */
     return () => {
       if (syncTimerRef.current !== null) {
         clearTimeout(syncTimerRef.current);

src/core/pushNotifications/isSqliteCloudNotification.ts

@@ -1,3 +1,4 @@
+/** SQLITE CLOUD ARTIFACT URI */
 const ARTIFACT_URI = 'https://sqlite.ai';
 
 /**
@@ -22,12 +23,12 @@ export const isForegroundSqliteCloudNotification = (
 export const isSqliteCloudNotification = (notification: any): boolean => {
   const body = notification?.data?.body;
 
-  // iOS background
+  /** CHECK IOS BACKGROUND FORMAT */
   if (body && typeof body === 'object' && body.artifactURI === ARTIFACT_URI) {
     return true;
   }
 
-  // Android background
+  /** CHECK ANDROID BACKGROUND FORMAT */
   const bodyString =
     typeof body === 'string' ? body : notification?.data?.dataString;
   if (typeof bodyString === 'string') {
@@ -41,6 +42,6 @@ export const isSqliteCloudNotification = (notification: any): boolean => {
     }
   }
 
-  // Foreground notification structure (fallback)
+  /** CHECK FOREGROUND FORMAT */
   return isForegroundSqliteCloudNotification(notification);
 };