From: Timo Tijhof <krinklemail@gmail.com>
Date: Tue, 4 Apr 2017 21:50:41 +0000 (-0700)
Subject: mediawiki.log: Improve documentation
X-Git-Tag: 1.31.0-rc.0~3604^2
X-Git-Url: http://git.cyclocoop.org/%22%20.%20generer_url_aide%28?a=commitdiff_plain;h=291a82aa241fbfafdefc43b791b8ed46e3a83439;p=lhc%2Fweb%2Fwiklou.git

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 0daac5b6ae..5e180b558a 100644
--- 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 4d23604ca1..969e872d11 100644
--- 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 ),