mediawiki.log: Improve documentation
[lhc/web/wiklou.git] / resources / src / mediawiki / mediawiki.js
index c2cee7e..5e180b5 100644 (file)
                        var results, i;
                        fallback = arguments.length > 1 ? fallback : null;
 
-                       if ( $.isArray( selection ) ) {
+                       if ( Array.isArray( selection ) ) {
                                results = {};
                                for ( i = 0; i < selection.length; i++ ) {
                                        if ( typeof selection[ i ] === 'string' ) {
                 */
                exists: function ( selection ) {
                        var i;
-                       if ( $.isArray( selection ) ) {
+                       if ( Array.isArray( selection ) ) {
                                for ( i = 0; i < selection.length; i++ ) {
                                        if ( typeof selection[ i ] !== 'string' || !hasOwn.call( this.values, selection[ i ] ) ) {
                                                return false;
 
        /* eslint-disable no-console */
        log = ( function () {
-               // Also update the restoration of methods in mediawiki.log.js
-               // when adding or removing methods here.
+               /**
+                * Write a verbose message to the browser's console in debug mode.
+                *
+                * This method is mainly intended for verbose logging. It is a no-op in production mode.
+                * In ResourceLoader debug mode, it will use the browser's console if available, with
+                * fallback to creating a console interface in the DOM and logging messages there.
+                *
+                * See {@link mw.log} for other logging methods.
+                *
+                * @member mw
+                * @param {...string} msg Messages to output to console.
+                */
                var log = function () {},
                        console = window.console;
 
+               // Note: Keep list of methods in sync with restoration in mediawiki.log.js
+               // when adding or removing mw.log methods below!
+
                /**
+                * Collection of methods to help log messages to the console.
+                *
                 * @class mw.log
                 * @singleton
                 */
 
                /**
-                * Write a message to the console's warning channel.
-                * Actions not supported by the browser console are silently ignored.
+                * Write a message to the browser console's warning channel.
+                *
+                * This method is a no-op in browsers that don't implement the Console API.
                 *
                 * @param {...string} msg Messages to output to console
                 */
                        $.noop;
 
                /**
-                * Write a message to the console's error channel.
+                * Write a message to the browser console's error channel.
+                *
+                * Most browsers also print a stacktrace when calling this method if the
+                * argument is an Error object.
                 *
-                * Most browsers provide a stacktrace by default if the argument
-                * is a caught Error object.
+                * This method is a no-op in browsers that don't implement the Console API.
                 *
                 * @since 1.26
                 * @param {Error|...string} msg Messages to output to console
                        $.noop;
 
                /**
-                * Create a property in a host object that, when accessed, will produce
+                * Create a property on a host object that, when accessed, will produce
                 * a deprecation warning in the console.
                 *
                 * @param {Object} obj Host object of deprecated property
                        return mw.message.apply( mw.message, arguments ).toString();
                },
 
-               /**
-                * No-op dummy placeholder for {@link mw.log} in debug mode.
-                *
-                * @method
-                */
+               // Expose mw.log
                log: log,
 
                /**
                         * @return {string} Hash of concatenated version hashes.
                         */
                        function getCombinedVersion( modules ) {
-                               var hashes = $.map( modules, function ( module ) {
+                               var hashes = modules.map( function ( module ) {
                                        return registry[ module ].version;
                                } );
                                return fnv132( hashes.join( '' ) );
 
                                        legacyWait.always( function () {
                                                try {
-                                                       if ( $.isArray( script ) ) {
+                                                       if ( Array.isArray( script ) ) {
                                                                nestedAddScript( script, markModuleReady, 0 );
                                                        } else if ( typeof script === 'function' ) {
                                                                // Pass jQuery twice so that the signature of the closure which wraps
 
                                                // Array of css strings in key 'css',
                                                // or back-compat array of urls from media-type
-                                               if ( $.isArray( value ) ) {
+                                               if ( Array.isArray( value ) ) {
                                                        for ( i = 0; i < value.length; i++ ) {
                                                                if ( key === 'bc-url' ) {
                                                                        // back-compat: { <media>: [url, ..] }
                                 * @return {Array}
                                 */
                                getModuleNames: function () {
-                                       return $.map( registry, function ( i, key ) {
-                                               return key;
-                                       } );
+                                       return Object.keys( registry );
                                },
 
                                /**
                // for all loading modules. If one fails, fall back to tracking each module
                // separately via $.when(), this is expensive.
                loading = mw.loader.using( loading ).then( null, function () {
-                       var all = $.map( loading, function ( module ) {
+                       var all = loading.map( function ( module ) {
                                return mw.loader.using( module ).then( null, function () {
                                        return $.Deferred().resolve();
                                } );