mediawiki.log: Improve documentation

* Clarify that all mw.log submethods use the native console
  when available and are otherwise no-ops. Their behaviour is
  not influenced by whether or not debug mode is enabled.

* Move mw.log() method doc to mediawiki.js and clarify that it
  is for verbose logging in debug mode (no-op in production mode).

Behaviour is not changed in this commit, only documentation.

Change-Id: Ie6e2382632654430dc57ee8c0a6222d6ad80663d

diff --git a/resources/src/mediawiki/mediawiki.js b/resources/src/mediawiki/mediawiki.js
index 0daac5b..5e180b5 100644 (file)
--- a/resources/src/mediawiki/mediawiki.js
+++ b/resources/src/mediawiki/mediawiki.js
@@ -419,19 +419,35 @@
 
        /* 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
                 */
@@ -440,10 +456,12 @@
                        $.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
@@ -453,7 +471,7 @@
                        $.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
@@ -702,11 +720,7 @@
                        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,
 
                /**

diff --git a/resources/src/mediawiki/mediawiki.log.js b/resources/src/mediawiki/mediawiki.log.js
index 4d23604..969e872 100644 (file)
--- a/resources/src/mediawiki/mediawiki.log.js
+++ b/resources/src/mediawiki/mediawiki.log.js
@@ -13,16 +13,6 @@
        var original = mw.log,
                slice = Array.prototype.slice;
 
-       /**
-        * Logs a message to the console in debug mode.
-        *
-        * In the case the browser does not have a console API, a console is created on-the-fly by appending
-        * a `<div id="mw-log-console">` element to the bottom of the body and then appending this and future
-        * messages to that, instead of the console.
-        *
-        * @member mw.log
-        * @param {...string} msg Messages to output to console.
-        */
        mw.log = function () {
                // Turn arguments into an array
                var args = slice.call( arguments ),