From 03aba1aa0d8d9fde437b1dadb5a46759865c8667 Mon Sep 17 00:00:00 2001
From: =?utf8?q?Bartosz=20Dziewo=C5=84ski?= <matma.rex@gmail.com>
Date: Sat, 1 Feb 2014 03:41:49 +0100
Subject: [PATCH] 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
---
 maintenance/jsduck/categories.json            |  1 +
 resources/mediawiki/mediawiki.notification.js | 28 +++++++++++--------
 2 files changed, 18 insertions(+), 11 deletions(-)

diff --git a/maintenance/jsduck/categories.json b/maintenance/jsduck/categories.json
index f1cd2f86f6..aa138bd326 100644
--- 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 4ede80961c..f142fa4183 100644
--- 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;
 		},
 
 		/**
-- 
2.20.1