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

diff --git a/RELEASE-NOTES-1.32 b/RELEASE-NOTES-1.32
index ec2597f..98c1a8e 100644 (file)
--- 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 0b6e616..fbc7b60 100644 (file)
--- 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 f3a83db..aa015a6 100644 (file)
--- 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 );
        }