docs: clarify added/removed events on device APIs (#34177)

docs/api/session.md

@@ -253,9 +253,11 @@ Returns:
   * `device` [HIDDevice[]](structures/hid-device.md)
   * `frame` [WebFrameMain](web-frame-main.md)
 
-Emitted when a new HID device becomes available. For example, when a new USB device is plugged in.
-
-This event will only be emitted after `navigator.hid.requestDevice` has been called and `select-hid-device` has fired.
+Emitted after `navigator.hid.requestDevice` has been called and
+`select-hid-device` has fired if a new device becomes available before
+the callback from `select-hid-device` is called.  This event is intended for
+use when using a UI to ask users to pick a device so that the UI can be updated
+with the newly added device.
 
 #### Event: 'hid-device-removed'
 
@@ -266,9 +268,11 @@ Returns:
   * `device` [HIDDevice[]](structures/hid-device.md)
   * `frame` [WebFrameMain](web-frame-main.md)
 
-Emitted when a HID device has been removed.  For example, this event will fire when a USB device is unplugged.
-
-This event will only be emitted after `navigator.hid.requestDevice` has been called and `select-hid-device` has fired.
+Emitted after `navigator.hid.requestDevice` has been called and
+`select-hid-device` has fired if a device has been removed before the callback
+from `select-hid-device` is called.  This event is intended for use when using
+a UI to ask users to pick a device so that the UI can be updated to remove the
+specified device.
 
 #### Event: 'select-serial-port'
 
@@ -348,7 +352,11 @@ Returns:
 * `port` [SerialPort](structures/serial-port.md)
 * `webContents` [WebContents](web-contents.md)
 
-Emitted after `navigator.serial.requestPort` has been called and `select-serial-port` has fired if a new serial port becomes available.  For example, this event will fire when a new USB device is plugged in.
+Emitted after `navigator.serial.requestPort` has been called and
+`select-serial-port` has fired if a new serial port becomes available before
+the callback from `select-serial-port` is called.  This event is intended for
+use when using a UI to ask users to pick a port so that the UI can be updated
+with the newly added port.
 
 #### Event: 'serial-port-removed'
 
@@ -358,7 +366,11 @@ Returns:
 * `port` [SerialPort](structures/serial-port.md)
 * `webContents` [WebContents](web-contents.md)
 
-Emitted after `navigator.serial.requestPort` has been called and `select-serial-port` has fired if a serial port has been removed.  For example, this event will fire when a USB device is unplugged.
+Emitted after `navigator.serial.requestPort` has been called and
+`select-serial-port` has fired if a serial port has been removed before the
+callback from `select-serial-port` is called.  This event is intended for use
+when using a UI to ask users to pick a port so that the UI can be updated
+to remove the specified port.
 
 ### Instance Methods
 

docs/fiddles/features/web-hid/main.js

@@ -8,18 +8,22 @@ function createWindow () {
   })
   
   mainWindow.webContents.session.on('select-hid-device', (event, details, callback) => {
-    event.preventDefault()
-    if (details.deviceList && details.deviceList.length > 0) {
-      callback(details.deviceList[0].deviceId)
-    }
-  })
-
+    //Add events to handle devices being added or removed before the callback on
+    //`select-hid-device` is called.
     mainWindow.webContents.session.on('hid-device-added', (event, device) => {    
       console.log('hid-device-added FIRED WITH', device)
+      //Optionally update details.deviceList
     })
   
     mainWindow.webContents.session.on('hid-device-removed', (event, device) => {    
       console.log('hid-device-removed FIRED WITH', device)
+      //Optionally update details.deviceList
+    })
+
+    event.preventDefault()
+    if (details.deviceList && details.deviceList.length > 0) {
+      callback(details.deviceList[0].deviceId)
+    }
   })
 
   mainWindow.webContents.session.setPermissionCheckHandler((webContents, permission, requestingOrigin, details) => {

docs/fiddles/features/web-serial/main.js

@@ -8,6 +8,19 @@ function createWindow () {
   })
   
   mainWindow.webContents.session.on('select-serial-port', (event, portList, webContents, callback) => {
+
+    //Add listeners to handle ports being added or removed before the callback for `select-serial-port`
+    //is called.
+    mainWindow.webContents.session.on('serial-port-added', (event, port) => {
+      console.log('serial-port-added FIRED WITH', port)
+      //Optionally update portList to add the new port
+    })
+  
+    mainWindow.webContents.session.on('serial-port-removed', (event, port) => {
+      console.log('serial-port-removed FIRED WITH', port)
+      //Optionally update portList to remove the port
+    })
+
     event.preventDefault()
     if (portList && portList.length > 0) {
       callback(portList[0].portId)
@@ -16,14 +29,6 @@ function createWindow () {
     }
   })
 
-  mainWindow.webContents.session.on('serial-port-added', (event, port) => {
-    console.log('serial-port-added FIRED WITH', port)
-  })
-
-  mainWindow.webContents.session.on('serial-port-removed', (event, port) => {
-    console.log('serial-port-removed FIRED WITH', port)
-  })
-
   mainWindow.webContents.session.setPermissionCheckHandler((webContents, permission, requestingOrigin, details) => {
     if (permission === 'serial' && details.securityOrigin === 'file:///') {
       return true

docs/tutorial/devices.md

@@ -36,8 +36,10 @@ the WebHID API:
   can be used to select a HID device when a call to
   `navigator.hid.requestDevice` is made.  Additionally the [`hid-device-added`](../api/session.md#event-hid-device-added)
   and [`hid-device-removed`](../api/session.md#event-hid-device-removed) events
-  on the Session can be used to handle devices being plugged in or unplugged during the
-  `navigator.hid.requestDevice` process.
+  on the Session can be used to handle devices being plugged in or unplugged
+  when handling the `select-hid-device` event.
+  **Note:** These events only fire until the callback from `select-hid-device`
+  is called.  They are not intended to be used as a generic hid device listener.
 * [`ses.setDevicePermissionHandler(handler)`](../api/session.md#sessetdevicepermissionhandlerhandler)
   can be used to provide default permissioning to devices without first calling
   for permission to devices via `navigator.hid.requestDevice`.  Additionally,
@@ -82,8 +84,11 @@ There are several additional APIs for working with the Web Serial API:
 
 * The [`serial-port-added`](../api/session.md#event-serial-port-added)
   and [`serial-port-removed`](../api/session.md#event-serial-port-removed) events
-  on the Session can be used to handle devices being plugged in or unplugged during the
-  `navigator.serial.requestPort` process.
+  on the Session can be used to handle devices being plugged in or unplugged
+  when handling the `select-serial-port` event.
+  **Note:** These events only fire until the callback from `select-serial-port`
+  is called.  They are not intended to be used as a generic serial port
+  listener.
 * [`ses.setDevicePermissionHandler(handler)`](../api/session.md#sessetdevicepermissionhandlerhandler)
   can be used to provide default permissioning to devices without first calling
   for permission to devices via `navigator.serial.requestPort`.  Additionally,