Make onUpdateAvailable documentation clearer.

extensions/common/api/runtime.json

 // Copyright 2014 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 // Note: Many of these functions and events are implemented by hand and should
 // not elicit any code generation from the schema compiler. These items are
 // marked "nocompile."
 [
   {
     "namespace": "runtime",
@@ skipping 359 matching lines @@
         "description": "Sent to the event page just before it is unloaded. This gives the extension opportunity to do some clean up. Note that since the page is unloading, any asynchronous operations started while handling this event are not guaranteed to complete. If more activity for the event page occurs before it gets unloaded the onSuspendCanceled event will be sent and the page won't be unloaded. "
       },
       {
         "name": "onSuspendCanceled",
         "type": "function",
         "description": "Sent after onSuspend to indicate that the app won't be unloaded after all."
       },
       {
         "name": "onUpdateAvailable",
         "type": "function",
-        "description": "Fired when an update is available, but isn't installed immediately because the app is currently running. If you do nothing, the update will be installed the next time the background page gets unloaded, if you want it to be installed sooner you can explicitly call chrome.runtime.reload().",
+        "description": "Fired when an update is available, but isn't installed immediately because the app is currently running. If you do nothing, the update will be installed the next time the background page gets unloaded, if you want it to be installed sooner you can explicitly call chrome.runtime.reload(). If your extension is using a persistent background page, the background page of course never gets unloaded, so unless you call chrome.runtime.reload() manually in response to this event the update will not get installed until the next time chrome itself restarts. If no handlers are listening for this event, and your extension has a persistent background page, it behaves as if chrome.runtime.reload() is called in response to this event.",
         "parameters": [
           {
             "type": "object",
             "name": "details",
             "properties": {
               "version": {
                 "type": "string",
                 "description": "The version number of the available update."
               }
             },
@@ skipping 82 matching lines @@
             "type": "string",
             "name": "reason",
             "description": "The reason that the event is being dispatched. 'app_update' is used when the restart is needed because the application is updated to a newer version. 'os_update' is used when the restart is needed because the browser/OS is updated to a newer version. 'periodic' is used when the system runs for more than the permitted uptime set in the enterprise policy.",
             "enum": ["app_update", "os_update", "periodic"]
           }
         ]
       }
     ]
   }
 ]