Clarify docs

docs/api/app.md

@@ -496,14 +496,20 @@ non-minimized.
 
 **Note:** If the second instance is started by a different user than the first, the `argv` array will not include the arguments.
 
-**Note:** `ackCallback` allows the user to send data back to the
-second instance during the `app.requestSingleInstanceLock()` flow.
+**Note:** `ackCallback` allows the user to pass some data from the
+first instance back to the second instance during the
+`app.requestSingleInstanceLock()` flow.
 This callback can be used for cases where the second instance
 needs to obtain additional information from the first instance
 before quitting.
-In order to call the callback, `event.preventDefault()` must be called
-Then, the `ackCallback` callback can be called.
+
+Currently, the limit on the message size is kMaxMessageLength,
+or around 32kB. To be safe, keep the amount of data passed to 31kB at most.
+
+In order to call the callback, `event.preventDefault()` must be called, first.
 If the callback is not called in either case, `null` will be sent back.
+If `event.preventDefault()` is not called, but `ackCallback` is called by
+the user in the event, then the behaviour is undefined.
 
 This event is guaranteed to be emitted after the `ready` event of `app`
 gets emitted.
@@ -978,13 +984,21 @@ starts:
 const { app } = require('electron')
 let myWindow = null
 
+app.on('first-instance-ack', (event, additionalData) => {
+  // Print out the ack received from the first instance.
+  // Note this event handler must come before the requestSingleInstanceLock call.
+  console.log(additionalData)
+})
+
 const additionalData = { myKey: 'myValue' }
 const gotTheLock = app.requestSingleInstanceLock(additionalData)
 
 if (!gotTheLock) {
   app.quit()
 } else {
-  app.on('second-instance', (event, commandLine, workingDirectory, additionalData) => {
+  app.on('second-instance', (event, commandLine, workingDirectory, additionalData, ackCallback) => {
+    // We must call preventDefault if we're sending back data.
+    event.preventDefault()
     // Print out data received from the second instance.
     console.log(additionalData)
 
@@ -993,6 +1007,8 @@ if (!gotTheLock) {
       if (myWindow.isMinimized()) myWindow.restore()
       myWindow.focus()
     }
+    const ackData = { myAckKey: 'myAckValue' }
+    ackCallback(ackData)
   })
 
   // Create myWindow, load the rest of the app, etc...