mw.loader: Document mw.loader.require() as private

[lhc/web/wiklou.git] / resources / src / mediawiki / mediawiki.js

diff --git a/resources/src/mediawiki/mediawiki.js b/resources/src/mediawiki/mediawiki.js
index a661ae5..a2e071e 100644 (file)
--- a/resources/src/mediawiki/mediawiki.js
+++ b/resources/src/mediawiki/mediawiki.js
@@ -53,7 +53,7 @@
        }
 
        function defineFallbacks() {
-               // <https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Set>
+               // <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set>
                StringSet = window.Set || ( function () {
                        /**
                         * @private
@@ -879,8 +879,10 @@
                                        // Cache
                                        marker = document.querySelector( 'meta[name="ResourceLoaderDynamicStyles"]' );
                                        if ( !marker ) {
-                                               mw.log( 'Create <meta name="ResourceLoaderDynamicStyles"> dynamically' );
-                                               marker = $( '<meta>' ).attr( 'name', 'ResourceLoaderDynamicStyles' ).appendTo( 'head' )[ 0 ];
+                                               mw.log( 'Created ResourceLoaderDynamicStyles marker dynamically' );
+                                               marker = document.createElement( 'meta' );
+                                               marker.name = 'ResourceLoaderDynamicStyles';
+                                               document.head.appendChild( marker );
                                        }
                                }
                                return marker;
@@ -902,7 +904,7 @@
                                if ( nextNode && nextNode.parentNode ) {
                                        nextNode.parentNode.insertBefore( s, nextNode );
                                } else {
-                                       document.getElementsByTagName( 'head' )[ 0 ].appendChild( s );
+                                       document.head.appendChild( s );
                                }
 
                                return s;
@@ -1980,6 +1982,12 @@
                                 *         OO.compare( [ 1 ], [ 1 ] );
                                 *     } );
                                 *
+                                * Example of inline dependency obtained via `require()`:
+                                *
+                                *     mw.loader.using( [ 'mediawiki.util' ], function ( require ) {
+                                *         var util = require( 'mediawiki.util' );
+                                *     } );
+                                *
                                 * Since MediaWiki 1.23 this also returns a promise.
                                 *
                                 * Since MediaWiki 1.28 the promise is resolved with a `require` function.
@@ -2059,7 +2067,7 @@
                                                                l = document.createElement( 'link' );
                                                                l.rel = 'stylesheet';
                                                                l.href = modules;
-                                                               $( 'head' ).append( l );
+                                                               document.head.appendChild( l );
                                                                return;
                                                        }
                                                        if ( type === 'text/javascript' || type === undefined ) {
@@ -2152,9 +2160,14 @@
                                /**
                                 * Get the exported value of a module.
                                 *
-                                * Modules may provide this via their local `module.exports`.
+                                * This static method is publicly exposed for debugging purposes
+                                * only and must not be used in production code. In production code,
+                                * please use the dynamically provided `require()` function instead.
                                 *
-                                * @protected
+                                * In case of lazy-loaded modules via mw.loader#using(), the returned
+                                * Promise provides the function, see #using() for examples.
+                                *
+                                * @private
                                 * @since 1.27
                                 * @param {string} moduleName Module name
                                 * @return {Mixed} Exported value
@@ -2753,7 +2766,7 @@
                        // If we have an exception object, log it to the warning channel to trigger
                        // proper stacktraces in browsers that support it.
                        if ( e && console.warn ) {
-                               console.warn( String( e ), e );
+                               console.warn( e );
                        }
                }
                /* eslint-enable no-console */
@@ -2778,9 +2791,9 @@
                // We only need a callback, not any actual module. First try a single using()
                // for all loading modules. If one fails, fall back to tracking each module
                // separately via $.when(), this is expensive.
-               loading = mw.loader.using( modules ).then( null, function () {
+               loading = mw.loader.using( modules ).catch( function () {
                        var all = modules.map( function ( module ) {
-                               return mw.loader.using( module ).then( null, function () {
+                               return mw.loader.using( module ).catch( function () {
                                        return $.Deferred().resolve();
                                } );
                        } );