From a63088d496c440e082009ef8c6901e364563db07 Mon Sep 17 00:00:00 2001
From: Timo Tijhof <krinklemail@gmail.com>
Date: Thu, 1 Mar 2018 17:21:32 -0800
Subject: [PATCH] resourceloader: Deprecate OutputPage::addModuleScripts()

And the counter-part in ParserOutput as well.

This follows-up on 80e5b160e0985, which removed the last use of this
method. It also deprecated ResourceLoaderClientHtml::setModuleScripts()
but that isn't usually used directly. The public interfaces are
mainly in OutputPage/ParserOutput, which are now deprecated as well.

Bug: T188689
Change-Id: I90baafdfc089ac03c4c3abc12065c0b60d43994e
---
 RELEASE-NOTES-1.32               |  2 ++
 includes/OutputPage.php          | 25 +++++++++++++------------
 includes/parser/ParserOutput.php | 10 ++++++++++
 3 files changed, 25 insertions(+), 12 deletions(-)

diff --git a/RELEASE-NOTES-1.32 b/RELEASE-NOTES-1.32
index ec2597fdba..98c1a8e807 100644
--- a/RELEASE-NOTES-1.32
+++ b/RELEASE-NOTES-1.32
@@ -80,6 +80,8 @@ changes to languages because of Phabricator reports.
 * Skin::setupSkinUserCss() is deprecated. Adding of modules to load
   has been centralised to Skin::getDefaultModules(), which is now capable
   of queueing style modules as well.
+* OutputPage::addModuleScripts() and ParserOutput::addModuleScripts are deprecated.
+  Use addModules() instead.
 
 === Other changes in 1.32 ===
 * …
diff --git a/includes/OutputPage.php b/includes/OutputPage.php
index 0b6e616b33..fbc7b60439 100644
--- a/includes/OutputPage.php
+++ b/includes/OutputPage.php
@@ -550,9 +550,7 @@ class OutputPage extends ContextSource {
 	}
 
 	/**
-	 * Add one or more modules recognized by ResourceLoader. Modules added
-	 * through this function will be loaded by ResourceLoader when the
-	 * page loads.
+	 * Load one or more ResourceLoader modules on this page.
 	 *
 	 * @param string|array $modules Module name (string) or array of module names
 	 */
@@ -561,7 +559,7 @@ class OutputPage extends ContextSource {
 	}
 
 	/**
-	 * Get the list of module JS to include on this page
+	 * Get the list of script-only modules to load on this page.
 	 *
 	 * @param bool $filter
 	 * @param string|null $position Unused
@@ -574,10 +572,13 @@ class OutputPage extends ContextSource {
 	}
 
 	/**
-	 * Add only JS of one or more modules recognized by ResourceLoader. Module
-	 * scripts added through this function will be loaded by ResourceLoader when
-	 * the page loads.
+	 * Load the scripts of one or more ResourceLoader modules, on this page.
 	 *
+	 * This method exists purely to provide the legacy behaviour of loading
+	 * a module's scripts in the global scope, and without dependency resolution.
+	 * See <https://phabricator.wikimedia.org/T188689>.
+	 *
+	 * @deprecated since 1.31 Use addModules() instead.
 	 * @param string|array $modules Module name (string) or array of module names
 	 */
 	public function addModuleScripts( $modules ) {
@@ -585,7 +586,7 @@ class OutputPage extends ContextSource {
 	}
 
 	/**
-	 * Get the list of module CSS to include on this page
+	 * Get the list of style-only modules to load on this page.
 	 *
 	 * @param bool $filter
 	 * @param string|null $position Unused
@@ -598,11 +599,11 @@ class OutputPage extends ContextSource {
 	}
 
 	/**
-	 * Add only CSS of one or more modules recognized by ResourceLoader.
+	 * Load the styles of one or more ResourceLoader modules on this page.
 	 *
-	 * Module styles added through this function will be added using standard link CSS
-	 * tags, rather than as a combined Javascript and CSS package. Thus, they will
-	 * load when JavaScript is disabled (unless CSS also happens to be disabled).
+	 * Module styles added through this function will be loaded as a stylesheet,
+	 * using a standard `<link rel=stylesheet>` HTML tag, rather than as a combined
+	 * Javascript and CSS package. Thus, they will even load when JavaScript is disabled.
 	 *
 	 * @param string|array $modules Module name (string) or array of module names
 	 */
diff --git a/includes/parser/ParserOutput.php b/includes/parser/ParserOutput.php
index f3a83dbe89..aa015a6eb1 100644
--- a/includes/parser/ParserOutput.php
+++ b/includes/parser/ParserOutput.php
@@ -744,14 +744,24 @@ class ParserOutput extends CacheTime {
 		}
 	}
 
+	/**
+	 * @see OutputPage::addModules
+	 */
 	public function addModules( $modules ) {
 		$this->mModules = array_merge( $this->mModules, (array)$modules );
 	}
 
+	/**
+	 * @deprecated since 1.31 Use addModules() instead.
+	 * @see OutputPage::addModuleScripts
+	 */
 	public function addModuleScripts( $modules ) {
 		$this->mModuleScripts = array_merge( $this->mModuleScripts, (array)$modules );
 	}
 
+	/**
+	 * @see OutputPage::addModuleStyles
+	 */
 	public function addModuleStyles( $modules ) {
 		$this->mModuleStyles = array_merge( $this->mModuleStyles, (array)$modules );
 	}
-- 
2.20.1