mediawiki.notification: Return the Notification object from .notify calls

The implementation is solid, stable and already includes sanity checks
that make it difficult to shoot oneself in the foot.

This essentially makes the class no longer private; adjusted
documentation accordingly.

Bug: 57400
Change-Id: Icecc75e05a1f9a46e8de984c401a0292817d0d4c

diff --git a/maintenance/jsduck/categories.json b/maintenance/jsduck/categories.json
index f1cd2f8..aa138bd 100644 (file)
--- a/maintenance/jsduck/categories.json
+++ b/maintenance/jsduck/categories.json
@@ -25,6 +25,7 @@
                                        "mw.inspect",
                                        "mw.inspect.reports",
                                        "mw.notification",
+                                       "mw.Notification_",
                                        "mw.user",
                                        "mw.util",
                                        "mw.plugin.*"

diff --git a/resources/mediawiki/mediawiki.notification.js b/resources/mediawiki/mediawiki.notification.js
index 4ede809..f142fa4 100644 (file)
--- a/resources/mediawiki/mediawiki.notification.js
+++ b/resources/mediawiki/mediawiki.notification.js
@@ -8,17 +8,17 @@
                preReadyNotifQueue = [];
 
        /**
-        * Creates a Notification object for 1 message.
-        * Does not insert anything into the document (see #start).
+        * A Notification object for 1 message.
         *
-        * The "_" in the name is to avoid a bug (http://github.com/senchalabs/jsduck/issues/304)
+        * The "_" in the name is to avoid a bug (http://github.com/senchalabs/jsduck/issues/304).
         * It is not part of the actual class name.
         *
         * @class mw.Notification_
         * @alternateClassName mw.Notification
-        * @private
         *
-        * @constructor
+        * @constructor The constructor is not publicly accessible; use mw.notification#notify instead.
+        *  This does not insert anything into the document (see #start).
+        * @private
         */
        function Notification( message, options ) {
                var $notification, $notificationTitle, $notificationContent;
@@ -75,9 +75,13 @@
        }
 
        /**
-        * Start the notification.
-        * This inserts it into the page, closes any matching tagged notifications,
-        * handles the fadeIn animations and repacement transitions, and starts autoHide timers.
+        * Start the notification. Called automatically by mw.notification#notify
+        * (possibly asynchronously on document-ready).
+        *
+        * This inserts the notification into the page, closes any matching tagged notifications,
+        * handles the fadeIn animations and replacement transitions, and starts autoHide timers.
+        *
+        * @private
         */
        Notification.prototype.start = function () {
                var
@@ -255,7 +259,6 @@
         * Close/hide the notification.
         *
         * @param {Object} options An object containing options for the closing of the notification.
-        *  These are typically only used internally.
         *
         *  - speed: Use a close speed different than the default 'slow'.
         *  - placeholder: Set to false to disable the placeholder transition.
@@ -332,6 +335,8 @@
         * Helper function, take a list of notification divs and call
         * a function on the Notification instance attached to them.
         *
+        * @private
+        * @static
         * @param {jQuery} $notifications A jQuery object containing notification divs
         * @param {string} fn The name of the function to call on the Notification instance
         */
@@ -426,7 +431,7 @@
                 * @param {HTMLElement|jQuery|mw.Message|string} message
                 * @param {Object} options The options to use for the notification.
                 *  See #defaults for details.
-                * @return {Object} Object with a close function to close the notification
+                * @return {mw.Notification} Notification object
                 */
                notify: function ( message, options ) {
                        var notif;
@@ -439,7 +444,8 @@
                        } else {
                                preReadyNotifQueue.push( notif );
                        }
-                       return { close: $.proxy( notif.close, notif ) };
+
+                       return notif;
                },
 
                /**