From fe469033d681de7675732d28fba79aa533ad1f0d Mon Sep 17 00:00:00 2001
From: Timo Tijhof <krinklemail@gmail.com>
Date: Mon, 22 Apr 2013 14:23:11 +0200
Subject: [PATCH] Implement mw.log.warn and mw.log.deprecate

Change-Id: I1eadd01d7086aecb1bdf7e950c49778fd63b5414
---
 RELEASE-NOTES-1.22                   |  3 ++
 maintenance/jsduck/categories.json   |  1 +
 resources/mediawiki/mediawiki.js     | 15 +++++---
 resources/mediawiki/mediawiki.log.js | 54 +++++++++++++++++++++++++---
 4 files changed, 64 insertions(+), 9 deletions(-)

diff --git a/RELEASE-NOTES-1.22 b/RELEASE-NOTES-1.22
index 23867d1318..02f0818398 100644
--- a/RELEASE-NOTES-1.22
+++ b/RELEASE-NOTES-1.22
@@ -58,6 +58,9 @@ production.
 * HTMLForm will turn multiselect checkboxes into a Chosen interface when setting cssclass 'mw-chosen'
 * rebuildLocalisationCache learned --lang option. Let you rebuild l10n caches
   of the specified languages instead of all of them.
+* mediawiki.log: Added log.warn wrapper (uses console.warn and console.trace).
+* mediawiki.log: Implemented log.deprecate. This method defines a property and
+  uses ES5 getter/setter to emit a warning when they are used.
 
 === Bug fixes in 1.22 ===
 * Disable Special:PasswordReset when $wgEnableEmail. Previously one could still
diff --git a/maintenance/jsduck/categories.json b/maintenance/jsduck/categories.json
index 7e7b381b48..97417c57b8 100644
--- a/maintenance/jsduck/categories.json
+++ b/maintenance/jsduck/categories.json
@@ -9,6 +9,7 @@
 					"mw.Map",
 					"mw.Message",
 					"mw.loader",
+					"mw.log",
 					"mw.html",
 					"mw.html.Cdata",
 					"mw.html.Raw"
diff --git a/resources/mediawiki/mediawiki.js b/resources/mediawiki/mediawiki.js
index 6c7e697889..716264d727 100644
--- a/resources/mediawiki/mediawiki.js
+++ b/resources/mediawiki/mediawiki.js
@@ -267,10 +267,17 @@ var mw = ( function ( $, undefined ) {
 		/* Public Members */
 
 		/**
-		 * Dummy function which in debug mode can be replaced with a function that
-		 * emulates console.log in console-less environments.
+		 * Dummy placeholder for {@link mw.log}
+		 * @method
 		 */
-		log: function () { },
+		log: ( function () {
+			var log = function () {};
+			log.warn = function () {};
+			log.deprecate = function ( obj, key, val ) {
+				obj[key] = val;
+			};
+			return log;
+		}() ),
 
 		// Make the Map constructor publicly available.
 		Map: Map,
@@ -294,8 +301,6 @@ var mw = ( function ( $, undefined ) {
 		 */
 		libs: {},
 
-		/* Extension points */
-
 		/**
 		 * @property
 		 */
diff --git a/resources/mediawiki/mediawiki.log.js b/resources/mediawiki/mediawiki.log.js
index e94f37ce4a..75e4c9610f 100644
--- a/resources/mediawiki/mediawiki.log.js
+++ b/resources/mediawiki/mediawiki.log.js
@@ -9,7 +9,8 @@
 ( function ( mw, $ ) {
 
 	/**
-	 * @class mw.plugin.log
+	 * @class mw.log
+	 * @singleton
 	 */
 
 	/**
@@ -58,7 +59,7 @@
 				hovzer.update();
 			}
 			$log.append(
-				$( '<div></div>' )
+				$( '<div>' )
 					.css( {
 						borderBottom: 'solid 1px #DDDDDD',
 						fontSize: 'small',
@@ -73,8 +74,53 @@
 	};
 
 	/**
-	 * @class mw
-	 * @mixins mw.plugin.log
+	 * Write a message the console's warning channel.
+	 * Also logs a stacktrace for easier debugging.
+	 * Each action is silently ignored if the browser doesn't support it.
+	 *
+	 * @param {string...} msg Messages to output to console
+	 */
+	mw.log.warn = function () {
+		var console = window.console;
+		if ( console && console.warn ) {
+			console.warn.apply( console, arguments );
+			if ( console.trace ) {
+				console.trace();
+			}
+		}
+	};
+
+	/**
+	 * Create a property in a host object that, when accessed, will produce
+	 * a deprecation warning in the console with backtrace.
+	 *
+	 * @param {Object} obj Host object of deprecated property
+	 * @param {string} key Name of property to create in `obj`
+	 * @param {Mixed} val The value this property should return when accessed
+	 * @param {string} [msg] Optional text to include in the deprecation message.
 	 */
+	mw.log.deprecate = !Object.defineProperty ? function ( obj, key, val ) {
+		obj[key] = val;
+	} : function ( obj, key, val, msg ) {
+		msg = 'MWDeprecationWarning: Use of "' + key + '" property is deprecated.' +
+			( msg ? ( ' ' + msg ) : '' );
+		try {
+			Object.defineProperty( obj, key, {
+				configurable: true,
+				enumerable: true,
+				get: function () {
+					mw.log.warn( msg );
+					return val;
+				},
+				set: function ( newVal ) {
+					mw.log.warn( msg );
+					val = newVal;
+				}
+			} );
+		} catch ( err ) {
+			// IE8 can throw on Object.defineProperty
+			obj[key] = val;
+		}
+	};
 
 }( mediaWiki, jQuery ) );
-- 
2.20.1