Update message documentation.

Describe `UserScriptUpdateNow`, and update it to make the caller more aware of the result.

Refs greasemonkey#2531

doc/Messages.md

@@ -191,6 +191,27 @@ Response data:
 
 * `null`, but presented upon async completion.
 
+# UserScriptUpdateNow
+Sent by: `browser/monkey-menu.js`
+Received by: `bg/updater.js`
+
+Triggered when the "Update Now" button of the manage user scripts dialog is clicked
+by the user.  Data:
+
+* `uuid` The UUID value of a script as returned by `ListUserScripts` message.
+
+Response data, an object with keys:
+
+* `result` A String, one of:
+  * `error` An unexpected error occurred.
+  * `ignore` The request was ignored; e.g. the script was uninstalled since the
+    update check was scheduled.
+  * `noupdate` The update check was successful, but there was no new version.
+  * `updated` The update check was successful, and there was a new version.
+* `details` If the result is `updated`, the script details of the newly
+  installed version.
+* `message` If the result is `error`, a message describing the failure.
+
 # UserScriptXhr
 Sent by: `content/api-provider-source.js`
 Received by: `bg/on-user-script-xhr.js`

src/bg/updater.js

@@ -14,7 +14,7 @@ function checkForUpdate(uuid) {
     let userScript = UserScriptRegistry.scriptByUuid(uuid);
     if (!userScript) {
       // Uninstalled since the update check was queued.
-      reject('ignore');
+      resolve({'result': 'ignore'});
       return;
     }
 
@@ -24,15 +24,14 @@ function checkForUpdate(uuid) {
       let downloader = new UserScriptDownloader();
       downloader.setScriptUrl(userScript.downloadUrl);
       downloader.start(details => {
-        // Return false here will stop the downloader -- skipping e.g.
-        // @require, @icon, etc. downloads.
         // `compareVersions()` returns -1 when its second argument is "larger".
         let comparison = compareVersions(userScript.version, details.version);
         // So we should abort if we don't get -1.
         abort = comparison !== -1;
-        // And we should return "not stop".
+        // Return false here will stop the downloader -- skipping e.g.
+        // @require, @icon, etc. downloads. So we should return "not abort".
         return !abort;
-      }).then(async () => {
+      }).then(async scriptDetails => {
         let window = fuzz(windowVal[windowKey] || MAX_UPDATE_IN_MS);
         if (abort) {
           window *= CHANGE_RATE;
@@ -49,12 +48,12 @@ function checkForUpdate(uuid) {
         chrome.storage.local.set(d, logUnhandledError);
 
         if (abort) {
-          resolve('no new version');
+          resolve({'result': 'noupdate'});
         } else {
-          resolve('updated');
+          resolve({'result': 'updated', 'details': scriptDetails});
         }
-      }).catch((e) => {
-        reject(e);
+      }).catch(e => {
+        reject({'result': 'error', 'message': e});
       });
     });
   });