docs: Make ipcRenderer and ipcMain listener API docs consistent (#44711)

* docs: Make ipcRenderer and ipcMain listener API docs consistent

Co-authored-by: Will Anderson <[email protected]>

* test: add some unit tests for ipcRenderer/ipcMain listener behavior

Co-authored-by: Will Anderson <[email protected]>

* fix: Mark on/off methods as primary and addListener/removeListener as aliases

Co-authored-by: Will Anderson <[email protected]>

* fix: clear all listeners before running ipcMain removeAllListeners tests

Co-authored-by: Will Anderson <[email protected]>

---------

Co-authored-by: trop[bot] <37223003+trop[bot]@users.noreply.github.com>
Co-authored-by: Will Anderson <[email protected]>

docs/api/ipc-main.md

@@ -32,7 +32,7 @@ process, see [webContents.send][web-contents-send] for more information.
 
 ## Methods
 
-The `ipcMain` module has the following method to listen for events:
+The `ipcMain` module has the following methods to listen for events:
 
 ### `ipcMain.on(channel, listener)`
 
@@ -44,6 +44,16 @@ The `ipcMain` module has the following method to listen for events:
 Listens to `channel`, when a new message arrives `listener` would be called with
 `listener(event, args...)`.
 
+### `ipcMain.off(channel, listener)`
+
+* `channel` string
+* `listener` Function
+  * `event` [IpcMainEvent][ipc-main-event]
+  * `...args` any[]
+
+Removes the specified `listener` from the listener array for the specified
+`channel`.
+
 ### `ipcMain.once(channel, listener)`
 
 * `channel` string
@@ -54,20 +64,28 @@ Listens to `channel`, when a new message arrives `listener` would be called with
 Adds a one time `listener` function for the event. This `listener` is invoked
 only the next time a message is sent to `channel`, after which it is removed.
 
+### `ipcMain.addListener(channel, listener)`
+
+* `channel` string
+* `listener` Function
+  * `event` [IpcMainEvent][ipc-main-event]
+  * `...args` any[]
+
+Alias for [`ipcMain.on`](#ipcmainonchannel-listener).
+
 ### `ipcMain.removeListener(channel, listener)`
 
 * `channel` string
 * `listener` Function
   * `...args` any[]
 
-Removes the specified `listener` from the listener array for the specified
-`channel`.
+Alias for [`ipcMain.off`](#ipcmainoffchannel-listener).
 
 ### `ipcMain.removeAllListeners([channel])`
 
 * `channel` string (optional)
 
-Removes listeners of the specified `channel`.
+Removes all listeners from the specified `channel`. Removes all listeners from all channels if no channel is specified.
 
 ### `ipcMain.handle(channel, listener)`
 

docs/api/ipc-renderer.md

@@ -48,7 +48,8 @@ Listens to `channel`, when a new message arrives `listener` would be called with
   * `event` [IpcRendererEvent][ipc-renderer-event]
   * `...args` any[]
 
-Alias for [`ipcRenderer.removeListener`](#ipcrendererremovelistenerchannel-listener).
+Removes the specified `listener` from the listener array for the specified
+`channel`.
 
 ### `ipcRenderer.once(channel, listener)`
 
@@ -76,14 +77,13 @@ Alias for [`ipcRenderer.on`](#ipcrendereronchannel-listener).
   * `event` [IpcRendererEvent][ipc-renderer-event]
   * `...args` any[]
 
-Removes the specified `listener` from the listener array for the specified
-`channel`.
+Alias for [`ipcRenderer.off`](#ipcrendereroffchannel-listener).
 
-### `ipcRenderer.removeAllListeners(channel)`
+### `ipcRenderer.removeAllListeners([channel])`
 
-* `channel` string
+* `channel` string (optional)
 
-Removes all listeners, or those of the specified `channel`.
+Removes all listeners from the specified `channel`. Removes all listeners from all channels if no channel is specified.
 
 ### `ipcRenderer.send(channel, ...args)`
 

spec/api-ipc-main-spec.ts

@@ -92,4 +92,27 @@ describe('ipc main module', () => {
       expect(v).to.equal('hello');
     });
   });
+
+  describe('ipcMain.removeAllListeners', () => {
+    beforeEach(() => { ipcMain.removeAllListeners(); });
+    beforeEach(() => { ipcMain.removeAllListeners(); });
+
+    it('removes only the given channel', () => {
+      ipcMain.on('channel1', () => {});
+      ipcMain.on('channel2', () => {});
+
+      ipcMain.removeAllListeners('channel1');
+
+      expect(ipcMain.eventNames()).to.deep.equal(['channel2']);
+    });
+
+    it('removes all channels if no channel is specified', () => {
+      ipcMain.on('channel1', () => {});
+      ipcMain.on('channel2', () => {});
+
+      ipcMain.removeAllListeners();
+
+      expect(ipcMain.eventNames()).to.deep.equal([]);
+    });
+  });
 });

spec/api-ipc-renderer-spec.ts

@@ -18,6 +18,7 @@ describe('ipcRenderer module', () => {
       }
     });
     await w.loadURL('about:blank');
+    w.webContents.on('console-message', (event, ...args) => console.error(...args));
   });
   after(async () => {
     await closeWindow(w);
@@ -144,6 +145,40 @@ describe('ipcRenderer module', () => {
     });
   });
 
+  describe('ipcRenderer.removeAllListeners', () => {
+    it('removes only the given channel', async () => {
+      const result = await w.webContents.executeJavaScript(`
+        (() => {
+          const { ipcRenderer } = require('electron');
+
+          ipcRenderer.on('channel1', () => {});
+          ipcRenderer.on('channel2', () => {});
+
+          ipcRenderer.removeAllListeners('channel1');
+
+          return ipcRenderer.eventNames();
+        })()
+      `);
+      expect(result).to.deep.equal(['channel2']);
+    });
+
+    it('removes all channels if no channel is specified', async () => {
+      const result = await w.webContents.executeJavaScript(`
+        (() => {
+          const { ipcRenderer } = require('electron');
+
+          ipcRenderer.on('channel1', () => {});
+          ipcRenderer.on('channel2', () => {});
+
+          ipcRenderer.removeAllListeners();
+
+          return ipcRenderer.eventNames();
+        })()
+      `);
+      expect(result).to.deep.equal([]);
+    });
+  });
+
   describe('after context is released', () => {
     it('throws an exception', async () => {
       const error = await w.webContents.executeJavaScript(`(${() => {