From 3edca1f02a659b17ef6c953c73a26ca646ddedeb Mon Sep 17 00:00:00 2001
From: Nico de Haen <ndh@deltachat.de>
Date: Wed, 11 Dec 2024 07:18:59 +0100
Subject: [PATCH] Add doc comments in notifications

---
 .../src/system-integration/notifications.ts   | 34 +++++++++------
 packages/target-electron/src/notifications.ts | 43 +++++++++++++------
 2 files changed, 52 insertions(+), 25 deletions(-)

diff --git a/packages/frontend/src/system-integration/notifications.ts b/packages/frontend/src/system-integration/notifications.ts
index e0a459cec..36d7cdee8 100644
--- a/packages/frontend/src/system-integration/notifications.ts
+++ b/packages/frontend/src/system-integration/notifications.ts
@@ -10,6 +10,28 @@ import type { T } from '@deltachat/jsonrpc-client'
 
 const log = getLogger('renderer/notifications')
 
+/**
+ * Notification handling:
+ *
+ * - listens for incoming notifications
+ * - reflects notification settings
+ * - prepares notification data (DcNotification)
+ * - queues notifications if needed to avoid "mass" notifications
+ * - sends notifications to runtime (which invokes ipcBackend)
+ */
+
+export function initNotifications() {
+  BackendRemote.on('IncomingMsg', (accountId, { chatId, msgId }) => {
+    incomingMessageHandler(accountId, chatId, msgId)
+  })
+  BackendRemote.on('IncomingWebxdcNotify', (accountId, { msgId }) => {
+    incomingWebxdcEventHandler(accountId, msgId)
+  })
+  BackendRemote.on('IncomingMsgBunch', accountId => {
+    flushNotifications(accountId)
+  })
+}
+
 function isMuted(accountId: number, chatId: number) {
   return BackendRemote.rpc.isChatMuted(accountId, chatId)
 }
@@ -294,15 +316,3 @@ function getNotificationIcon(
     return null
   }
 }
-
-export function initNotifications() {
-  BackendRemote.on('IncomingMsg', (accountId, { chatId, msgId }) => {
-    incomingMessageHandler(accountId, chatId, msgId)
-  })
-  BackendRemote.on('IncomingWebxdcNotify', (accountId, { msgId }) => {
-    incomingWebxdcEventHandler(accountId, msgId)
-  })
-  BackendRemote.on('IncomingMsgBunch', accountId => {
-    flushNotifications(accountId)
-  })
-}
diff --git a/packages/target-electron/src/notifications.ts b/packages/target-electron/src/notifications.ts
index c11888eeb..b2938dff8 100644
--- a/packages/target-electron/src/notifications.ts
+++ b/packages/target-electron/src/notifications.ts
@@ -8,10 +8,34 @@ import { getLogger } from '../../shared/logger.js'
 
 import type { NativeImage, IpcMainInvokeEvent } from 'electron'
 
+/**
+ * Notification related functions to:
+ * - show notifications in operating system
+ * - handle click on notification
+ *
+ * is triggered from renderer process (!)
+ * by handling events (ipcMain.handle)
+ *
+ * see: frontend/src/system-integration/notifications.ts
+ */
+
 const log = getLogger('main/notifications')
 
 const isMac = platform() === 'darwin'
 
+if (Notification.isSupported()) {
+  ipcMain.handle('notifications.show', showNotification)
+  ipcMain.handle('notifications.clear', clearNotificationsForChat)
+  ipcMain.handle('notifications.clearAll', clearAll)
+  process.on('beforeExit', clearAll)
+} else {
+  // Register no-op handlers for notifications to silently fail when
+  // no notifications are supported
+  ipcMain.handle('notifications.show', () => {})
+  ipcMain.handle('notifications.clear', () => {})
+  ipcMain.handle('notifications.clearAll', () => {})
+}
+
 function createNotification(data: DcNotification): Notification {
   let icon: NativeImage | undefined = data.icon
     ? data.icon.indexOf('base64') > -1
@@ -69,6 +93,12 @@ function onClickNotification(
 
 const notifications: { [chatId: number]: Notification[] } = {}
 
+/**
+ * triggers creation of a notification, adds appropriate
+ * callbacks and shows it via electron Notification API
+ *
+ * @param data is passed from renderer process
+ */
 function showNotification(_event: IpcMainInvokeEvent, data: DcNotification) {
   const chatId = data.chatId
 
@@ -135,19 +165,6 @@ function clearAll() {
   }
 }
 
-if (Notification.isSupported()) {
-  ipcMain.handle('notifications.show', showNotification)
-  ipcMain.handle('notifications.clear', clearNotificationsForChat)
-  ipcMain.handle('notifications.clearAll', clearAll)
-  process.on('beforeExit', clearAll)
-} else {
-  // Register no-op handlers for notifications to silently fail when
-  // no notifications are supported
-  ipcMain.handle('notifications.show', () => {})
-  ipcMain.handle('notifications.clear', () => {})
-  ipcMain.handle('notifications.clearAll', () => {})
-}
-
 // Thanks to Signal for this function
 // https://github.com/signalapp/Signal-Desktop/blob/ae9181a4b26264ce553c7d8379a3ee5a07de018b/ts/services/notifications.ts#L485
 // it is licensed AGPL-3.0-only