Implement mw.log.warn and mw.log.deprecate

Change-Id: I1eadd01d7086aecb1bdf7e950c49778fd63b5414

diff --git a/RELEASE-NOTES-1.22 b/RELEASE-NOTES-1.22
index 23867d1..02f0818 100644 (file)
--- 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 7e7b381..97417c5 100644 (file)
--- 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 6c7e697..716264d 100644 (file)
--- 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 e94f37c..75e4c96 100644 (file)
--- 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 ) );