Merge branch 'master' of https://github.com/mozilla/addon-sdk

packages/addon-kit/docs/notifications.md

@@ -1,11 +1,18 @@
 <!-- contributed by Drew Willcoxon [adw@mozilla.com]  -->
 
-The `notifications` module allows you to display transient [toaster]()- or
-[Growl]()-style messages to the user.
+The `notifications` module allows you to display transient, [toaster][]-style
+desktop messages to the user.
+
+This API supports desktop notifications on Windows, OS X using [Growl][], and
+Linux using libnotify.  If the user's system does not support desktop
+notifications or if its notifications service is not running, then notifications
+made with this API are logged to Firefox's error console and, if the user
+launched Firefox from the command line, the terminal.
 
 [toaster]: http://en.wikipedia.org/wiki/Toast_%28computing%29
 [Growl]: http://growl.info/
 
+
 Examples
 --------
 
@@ -19,13 +26,12 @@ the console.
       data: "did gyre and gimble in the wabe",
       onClick: function (data) {
         console.log(data);
-        // console.log(this.data) would produce the
-        // same result in this case.
+        // console.log(this.data) would produce the same result.
       }
     });
 
 This one displays an icon that's stored in the add-on's `data` directory.  (See
-the `self` module documentation for more information.)
+the [`self`](#module/api-utils/self) module documentation for more information.)
 
     var notifications = require("notifications");
     var self = require("self");
@@ -47,7 +53,8 @@ the `self` module documentation for more information.)
     A string to display as the body of the message.
   @prop [iconURL] {string}
     The URL of an icon to display inside the message.  It may be a remote URL,
-    a data URI, or a URL returned by the `self` module.
+    a data URI, or a URL returned by the [`self`](#module/api-utils/self)
+    module.
   @prop [onClick] {function}
     A function to be called when the user clicks the message.  It will be passed
     the value of `data`.

packages/addon-kit/docs/page-mod.md

@@ -149,9 +149,11 @@ attached and registers a listener function that simply logs the message:
 
 The console output of this add-on is:
 
-    info: Attaching content scripts
-    info: Content script 1 is attached to http://www.mozilla.com/en-US/
-    info: Content script 2 is attached to http://www.mozilla.com/en-US/
+<pre>
+  info: Attaching content scripts
+  info: Content script 1 is attached to http://www.mozilla.com/en-US/
+  info: Content script 2 is attached to http://www.mozilla.com/en-US/
+</pre>
 
 <api name="PageMod">
 @class

packages/addon-kit/docs/private-browsing.md

@@ -1,4 +1,4 @@
-<!-- contributed by Paul O’Shannessy [paul@oshannessy.com]  -->
+<!-- contributed by Paul O'Shannessy [paul@oshannessy.com]  -->
 <!-- edited by Noelle Murata [fiveinchpixie@gmail.com]  -->
 <!-- contributed by Irakli Gozalishvili [gozala@mozilla.com] -->
 

packages/addon-kit/docs/widget.md

@@ -152,7 +152,7 @@ create your content scripts in separate files and pass their URLs using the
       contentScript: 'on("message", function(message) {' +
                      '  alert("Got message: " + message);' +
                      '});' +
-                     'postMessage("ready");",
+                     'postMessage("ready");',
       onMessage: function(message) {
         if (message == "ready")
           widget.postMessage("me too");

packages/addon-kit/lib/notifications.js

@@ -37,27 +37,22 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
-const { Cc, Ci } = require("chrome");
+const { Cc, Ci, Cr } = require("chrome");
 const apiUtils = require("api-utils");
 const errors = require("errors");
 
 try {
-  // The unit test sets this to a mock alert service.
-  var gAlertServ = Cc["@mozilla.org/alerts-service;1"].
-                   getService(Ci.nsIAlertsService);
+  let alertServ = Cc["@mozilla.org/alerts-service;1"].
+                  getService(Ci.nsIAlertsService);
+
+  // The unit test sets this to a mock notification function.
+  var notify = alertServ.showAlertNotification.bind(alertServ);
 }
 catch (err) {
   // An exception will be thrown if the platform doesn't provide an alert
-  // service, e.g., if Growl is not installed on OS X.  In that case, create a
-  // mock alert service that just logs to the console.
-  gAlertServ = {
-    showAlertNotification: function (iconURL, title, text) {
-      title = title ? "[" + title + "]" : "";
-      text = text || "";
-      let str = [title, text].filter(function (s) s).join(" ");
-      console.log(str);
-    }
-  };
+  // service, e.g., if Growl is not installed on OS X.  In that case, use a
+  // mock notification function that just logs to the console.
+  notify = notifyUsingConsole;
 }
 
 exports.notify = function notifications_notify(options) {
@@ -68,11 +63,32 @@ exports.notify = function notifications_notify(options) {
         errors.catchAndLog(valOpts.onClick).call(exports, valOpts.data);
     }
   };
-  gAlertServ.showAlertNotification(valOpts.iconURL, valOpts.title,
-                                   valOpts.text, !!clickObserver, valOpts.data,
-                                   clickObserver);
+  function notifyWithOpts(notifyFn) {
+    notifyFn(valOpts.iconURL, valOpts.title, valOpts.text, !!clickObserver,
+             valOpts.data, clickObserver);
+  }
+  try {
+    notifyWithOpts(notify);
+  }
+  catch (err if err instanceof Ci.nsIException &&
+                err.result == Cr.NS_ERROR_FILE_NOT_FOUND) {
+    console.warn("The notification icon named by " + valOpts.iconURL +
+                 " does not exist.  A default icon will be used instead.");
+    delete valOpts.iconURL;
+    notifyWithOpts(notify);
+  }
+  catch (err) {
+    notifyWithOpts(notifyUsingConsole);
+  }
 };
 
+function notifyUsingConsole(iconURL, title, text) {
+  title = title ? "[" + title + "]" : "";
+  text = text || "";
+  let str = [title, text].filter(function (s) s).join(" ");
+  console.log(str);
+}
+
 function validateOptions(options) {
   return apiUtils.validateOptions(options, {
     data: {

packages/addon-kit/lib/panel.js

@@ -177,16 +177,14 @@ const Panel = Symbiont.resolve({
       xulPanel.hidePopup();
     return this._public;
   },
-  
+
   /* Public API: Panel.resize */
   resize: function resize(width, height) {
     this.width = width;
     this.height = height;
     this._xulPanel.sizeTo(width, height);
   },
-
-  // While the panel is visible, this is the XUL <panel> we use to display it.
-  // Otherwise, it's null.
+
   // While the panel is visible, this is the XUL <panel> we use to display it.
   // Otherwise, it's null.
   get _xulPanel() this.__xulPanel,

packages/addon-kit/tests/test-notifications.js

@@ -71,6 +71,6 @@ function makeLoader(test) {
     }
   };
   let scope = loader.findSandboxForModule("notifications").globalScope;
-  scope.gAlertServ = mockAlertServ;
+  scope.notify = mockAlertServ.showAlertNotification.bind(mockAlertServ);
   return [loader, mockAlertServ];
 };

packages/api-utils/docs/collection.md

@@ -20,9 +20,11 @@ order they were added.  For example, the following code...
 
 ... would print this to the console:
 
-    1
-    2
-    3
+<pre>
+  1
+  2
+  3
+</pre>
 
 Iteration proceeds over a copy of the collection made before iteration begins,
 so it is safe to mutate the collection during iteration; doing so does not

python-lib/cuddlefish/apiparser.py

@@ -1,5 +1,7 @@
 import sys, re, textwrap
 
+VERSION = 2
+
 class ParseError(Exception):
     # args[1] is the line number that caused the problem
     def __init__(self, why, lineno):
@@ -239,6 +241,7 @@ def parse_hunks(text):
     # return a list of tuples. Each is one of:
     #    ("raw", string)         : non-API blocks
     #    ("api-json", dict)  : API blocks
+    yield ("version", VERSION)
     lines = text.splitlines(True)
     line_number = 0
     markdown_string = ""