From f8a0e34ca1b8584660dc9a6867a5b0bfdf80f3f1 Mon Sep 17 00:00:00 2001 From: Sam Reed Date: Fri, 14 Oct 2011 08:06:54 +0000 Subject: [PATCH] Documentation Trim trailing whitespace Make returns return values where appropriate (ie other paths in the same method do) --- includes/resourceloader/ResourceLoader.php | 25 +++++++---- .../resourceloader/ResourceLoaderContext.php | 13 ++++-- .../ResourceLoaderFileModule.php | 15 ++++++- .../ResourceLoaderFilePageModule.php | 7 ++- .../resourceloader/ResourceLoaderModule.php | 45 ++++++++++--------- .../ResourceLoaderStartUpModule.php | 3 ++ .../ResourceLoaderUserModule.php | 8 ++-- .../ResourceLoaderUserOptionsModule.php | 11 +++-- .../ResourceLoaderUserTokensModule.php | 9 ++-- .../ResourceLoaderWikiModule.php | 36 ++++++++------- 10 files changed, 108 insertions(+), 64 deletions(-) diff --git a/includes/resourceloader/ResourceLoader.php b/includes/resourceloader/ResourceLoader.php index 1a4817aae9..ef698f808f 100644 --- a/includes/resourceloader/ResourceLoader.php +++ b/includes/resourceloader/ResourceLoader.php @@ -263,10 +263,10 @@ class ResourceLoader { /** * Add a foreign source of modules. - * + * * Source properties: * 'loadScript': URL (either fully-qualified or protocol-relative) of load.php for this source - * + * * @param $id Mixed: source ID (string), or array( id1 => props1, id2 => props2, ... ) * @param $properties Array: source properties */ @@ -340,7 +340,7 @@ class ResourceLoader { /** * Get the list of sources - * + * * @return Array: array( id => array of properties, .. ) */ public function getSources() { @@ -401,6 +401,9 @@ class ResourceLoader { // the last modified time $mtime = wfTimestamp( TS_UNIX, $wgCacheEpoch ); foreach ( $modules as $module ) { + /** + * @var $module ResourceLoaderModule + */ try { // Bypass Squid and other shared caches if the request includes any private modules if ( $module->getGroup() === 'private' ) { @@ -571,7 +574,7 @@ class ResourceLoader { $this->sendResponseHeaders( $context, $ts, false ); // If there's an If-Modified-Since header, respond with a 304 appropriately if ( $this->tryRespondLastModified( $context, $ts ) ) { - return; // output handled (buffers cleared) + return false; // output handled (buffers cleared) } $response = $fileCache->fetchText(); // Remove the output buffer and output the response @@ -617,6 +620,10 @@ class ResourceLoader { // Generate output foreach ( $modules as $name => $module ) { + /** + * @var $module ResourceLoaderModule + */ + wfProfileIn( __METHOD__ . '-' . $name ); try { $scripts = ''; @@ -876,13 +883,13 @@ class ResourceLoader { /** * Returns JS code which calls mw.loader.addSource() with the given * parameters. Has two calling conventions: - * + * * - ResourceLoader::makeLoaderSourcesScript( $id, $properties ): * Register a single source - * + * * - ResourceLoader::makeLoaderSourcesScript( array( $id1 => $props1, $id2 => $props2, ... ) ); * Register sources with the given IDs and properties. - * + * * @param $id String: source ID * @param $properties Array: source properties (see addSource()) * @@ -982,7 +989,7 @@ class ResourceLoader { $query = self::makeLoaderQuery( $modules, $lang, $skin, $user, $version, $debug, $only, $printable, $handheld, $extraQuery ); - + // Prevent the IE6 extension check from being triggered (bug 28840) // by appending a character that's invalid in Windows extensions ('*') return wfExpandUrl( wfAppendQuery( $wgLoadScript, $query ) . '&*', PROTO_RELATIVE ); @@ -1017,7 +1024,7 @@ class ResourceLoader { $query['handheld'] = 1; } $query += $extraQuery; - + // Make queries uniform in order ksort( $query ); return $query; diff --git a/includes/resourceloader/ResourceLoaderContext.php b/includes/resourceloader/ResourceLoaderContext.php index 7e70713505..2a5169aa9d 100644 --- a/includes/resourceloader/ResourceLoaderContext.php +++ b/includes/resourceloader/ResourceLoaderContext.php @@ -21,7 +21,7 @@ */ /** - * Object passed around to modules which contains information about the state + * Object passed around to modules which contains information about the state * of a specific loader request */ class ResourceLoaderContext { @@ -42,6 +42,10 @@ class ResourceLoaderContext { /* Methods */ + /** + * @param $resourceLoader ResourceLoader + * @param $request WebRequest + */ public function __construct( $resourceLoader, WebRequest $request ) { global $wgDefaultSkin, $wgResourceLoaderDebug; @@ -63,7 +67,7 @@ class ResourceLoaderContext { $this->skin = $wgDefaultSkin; } } - + /** * Expand a string of the form jquery.foo,bar|jquery.ui.baz,quux to * an array of module names like array( 'jquery.foo', 'jquery.bar', @@ -99,9 +103,10 @@ class ResourceLoaderContext { } return $retval; } - + /** * Return a dummy ResourceLoaderContext object suitable for passing into things that don't "really" need a context + * @return ResourceLoaderContext */ public static function newDummyContext() { return new self( null, new FauxRequest( array() ) ); @@ -218,7 +223,7 @@ class ResourceLoaderContext { public function getHash() { if ( !isset( $this->hash ) ) { $this->hash = implode( '|', array( - $this->getLanguage(), $this->getDirection(), $this->skin, $this->user, + $this->getLanguage(), $this->getDirection(), $this->skin, $this->user, $this->debug, $this->only, $this->version ) ); } diff --git a/includes/resourceloader/ResourceLoaderFileModule.php b/includes/resourceloader/ResourceLoaderFileModule.php index 73ae0d2d98..00bec82559 100644 --- a/includes/resourceloader/ResourceLoaderFileModule.php +++ b/includes/resourceloader/ResourceLoaderFileModule.php @@ -223,7 +223,11 @@ class ResourceLoaderFileModule extends ResourceLoaderModule { $files = $this->getScriptFiles( $context ); return $this->readScriptFiles( $files ); } - + + /** + * @param $context ResourceLoaderContext + * @return array + */ public function getScriptURLsForDebug( ResourceLoaderContext $context ) { $urls = array(); foreach ( $this->getScriptFiles( $context ) as $file ) { @@ -232,6 +236,9 @@ class ResourceLoaderFileModule extends ResourceLoaderModule { return $urls; } + /** + * @return bool + */ public function supportsURLLoading() { return $this->debugRaw; } @@ -275,6 +282,10 @@ class ResourceLoaderFileModule extends ResourceLoaderModule { return $styles; } + /** + * @param $context ResourceLoaderContext + * @return array + */ public function getStyleURLsForDebug( ResourceLoaderContext $context ) { $urls = array(); foreach ( $this->getStyleFiles( $context ) as $mediaType => $list ) { @@ -582,7 +593,7 @@ class ResourceLoaderFileModule extends ResourceLoaderModule { $style, $dir, $remoteDir, true ); } - + /** * Safe version of filemtime(), which doesn't throw a PHP warning if the file doesn't exist * but returns 1 instead. diff --git a/includes/resourceloader/ResourceLoaderFilePageModule.php b/includes/resourceloader/ResourceLoaderFilePageModule.php index fc9aef1bed..e3b719bb93 100644 --- a/includes/resourceloader/ResourceLoaderFilePageModule.php +++ b/includes/resourceloader/ResourceLoaderFilePageModule.php @@ -1,8 +1,13 @@ array( 'type' => 'style' ), diff --git a/includes/resourceloader/ResourceLoaderModule.php b/includes/resourceloader/ResourceLoaderModule.php index 14a92bd1a4..6db5fb695e 100644 --- a/includes/resourceloader/ResourceLoaderModule.php +++ b/includes/resourceloader/ResourceLoaderModule.php @@ -52,11 +52,11 @@ abstract class ResourceLoaderModule { # limit the types of scripts and styles we allow to load on, say, sensitive special # pages like Special:UserLogin and Special:Preferences protected $origin = self::ORIGIN_CORE_SITEWIDE; - + /* Protected Members */ protected $name = null; - + // In-object cache for file dependencies protected $fileDeps = array(); // In-object cache for message blob mtime @@ -126,18 +126,18 @@ abstract class ResourceLoaderModule { // Stub, override expected return ''; } - + /** * Get the URL or URLs to load for this module's JS in debug mode. * The default behavior is to return a load.php?only=scripts URL for * the module, but file-based modules will want to override this to * load the files directly. - * + * * This function is called only when 1) we're in debug mode, 2) there * is no only= parameter and 3) supportsURLLoading() returns true. * #2 is important to prevent an infinite loop, therefore this function * MUST return either an only= URL or a non-load.php URL. - * + * * @param $context ResourceLoaderContext: Context object * @return Array of URLs */ @@ -155,7 +155,7 @@ abstract class ResourceLoaderModule { ); return array( $url ); } - + /** * Whether this module supports URL loading. If this function returns false, * getScript() will be used even in cases (debug mode, no only param) where @@ -176,13 +176,13 @@ abstract class ResourceLoaderModule { // Stub, override expected return array(); } - + /** * Get the URL or URLs to load for this module's CSS in debug mode. * The default behavior is to return a load.php?only=styles URL for * the module, but file-based modules will want to override this to * load the files directly. See also getScriptURLsForDebug() - * + * * @param $context ResourceLoaderContext: Context object * @return Array: array( mediaType => array( URL1, URL2, ... ), ... ) */ @@ -212,10 +212,10 @@ abstract class ResourceLoaderModule { // Stub, override expected return array(); } - + /** * Get the group this module is in. - * + * * @return String: Group name */ public function getGroup() { @@ -225,14 +225,14 @@ abstract class ResourceLoaderModule { /** * Get the origin of this module. Should only be overridden for foreign modules. - * + * * @return String: Origin name, 'local' for local modules */ public function getSource() { // Stub, override expected return 'local'; } - + /** * Where on the HTML page should this module's JS be loaded? * 'top': in the @@ -273,7 +273,7 @@ abstract class ResourceLoaderModule { // Stub, override expected return array(); } - + /** * Get the files this module depends on indirectly for a given skin. * Currently these are only image files referenced by the module's CSS. @@ -300,7 +300,7 @@ abstract class ResourceLoaderModule { } return $this->fileDeps[$skin]; } - + /** * Set preloaded file dependency information. Used so we can load this * information for all modules at once. @@ -310,7 +310,7 @@ abstract class ResourceLoaderModule { public function setFileDependencies( $skin, $deps ) { $this->fileDeps[$skin] = $deps; } - + /** * Get the last modification timestamp of the message blob for this * module in a given language. @@ -321,7 +321,7 @@ abstract class ResourceLoaderModule { if ( !isset( $this->msgBlobMtime[$lang] ) ) { if ( !count( $this->getMessages() ) ) return 0; - + $dbr = wfGetDB( DB_SLAVE ); $msgBlobMtime = $dbr->selectField( 'msg_resource', 'mr_timestamp', array( 'mr_resource' => $this->getName(), @@ -337,7 +337,7 @@ abstract class ResourceLoaderModule { } return $this->msgBlobMtime[$lang]; } - + /** * Set a preloaded message blob last modification timestamp. Used so we * can load this information for all modules at once. @@ -347,9 +347,9 @@ abstract class ResourceLoaderModule { public function setMsgBlobMtime( $lang, $mtime ) { $this->msgBlobMtime[$lang] = $mtime; } - + /* Abstract Methods */ - + /** * Get this module's last modification timestamp for a given * combination of language, skin and debug mode flag. This is typically @@ -364,7 +364,7 @@ abstract class ResourceLoaderModule { // 0 would mean now return 1; } - + /** * Check whether this module is known to be empty. If a child class * has an easy and cheap way to determine that this module is @@ -412,7 +412,7 @@ abstract class ResourceLoaderModule { $err = $e->getMessage(); $result = "throw new Error(" . Xml::encodeJsVar("JavaScript parse error: $err") . ");"; } - + $cache->set( $key, $result ); return $result; } else { @@ -420,6 +420,9 @@ abstract class ResourceLoaderModule { } } + /** + * @return JSParser + */ protected static function javaScriptParser() { if ( !self::$jsParser ) { self::$jsParser = new JSParser(); diff --git a/includes/resourceloader/ResourceLoaderStartUpModule.php b/includes/resourceloader/ResourceLoaderStartUpModule.php index 7b819def06..bb3a039b7e 100644 --- a/includes/resourceloader/ResourceLoaderStartUpModule.php +++ b/includes/resourceloader/ResourceLoaderStartUpModule.php @@ -241,6 +241,9 @@ class ResourceLoaderStartUpModule extends ResourceLoaderModule { return $out; } + /** + * @return bool + */ public function supportsURLLoading() { return false; } diff --git a/includes/resourceloader/ResourceLoaderUserModule.php b/includes/resourceloader/ResourceLoaderUserModule.php index 3c6f61e2f9..338b6322ee 100644 --- a/includes/resourceloader/ResourceLoaderUserModule.php +++ b/includes/resourceloader/ResourceLoaderUserModule.php @@ -38,16 +38,16 @@ class ResourceLoaderUserModule extends ResourceLoaderWikiModule { $username = $context->getUser(); $userpageTitle = Title::makeTitleSafe( NS_USER, $username ); $userpage = $userpageTitle->getPrefixedDBkey(); // Needed so $excludepages works - + $pages = array( "$userpage/common.js" => array( 'type' => 'script' ), - "$userpage/" . $context->getSkin() . '.js' => + "$userpage/" . $context->getSkin() . '.js' => array( 'type' => 'script' ), "$userpage/common.css" => array( 'type' => 'style' ), - "$userpage/" . $context->getSkin() . '.css' => + "$userpage/" . $context->getSkin() . '.css' => array( 'type' => 'style' ), ); - + // Hack for bug 26283: if we're on a preview page for a CSS/JS page, // we need to exclude that page from this module. In that case, the excludepage // parameter will be set to the name of the page we need to exclude. diff --git a/includes/resourceloader/ResourceLoaderUserOptionsModule.php b/includes/resourceloader/ResourceLoaderUserOptionsModule.php index 24152b5ccc..355c43ade7 100644 --- a/includes/resourceloader/ResourceLoaderUserOptionsModule.php +++ b/includes/resourceloader/ResourceLoaderUserOptionsModule.php @@ -55,7 +55,7 @@ class ResourceLoaderUserOptionsModule extends ResourceLoaderModule { /** * Fetch the context's user options, or if it doesn't match current user, * the default options. - * + * * @param $context ResourceLoaderContext: Context object * @return Array: List of user options keyed by option name */ @@ -75,7 +75,7 @@ class ResourceLoaderUserOptionsModule extends ResourceLoaderModule { * @return string */ public function getScript( ResourceLoaderContext $context ) { - return Xml::encodeJsCall( 'mw.user.options.set', + return Xml::encodeJsCall( 'mw.user.options.set', array( $this->contextUserOptions( $context ) ) ); } @@ -96,7 +96,7 @@ class ResourceLoaderUserOptionsModule extends ResourceLoaderModule { // Underline: 2 = browser default, 1 = always, 0 = never if ( $options['underline'] < 2 ) { - $rules[] = "a { text-decoration: " . + $rules[] = "a { text-decoration: " . ( $options['underline'] ? 'underline !important' : 'none' ) . "; }"; } if ( $options['highlightbroken'] ) { @@ -133,7 +133,10 @@ class ResourceLoaderUserOptionsModule extends ResourceLoaderModule { public function getGroup() { return 'private'; } - + + /** + * @return array + */ public function getDependencies() { return array( 'mediawiki.user' ); } diff --git a/includes/resourceloader/ResourceLoaderUserTokensModule.php b/includes/resourceloader/ResourceLoaderUserTokensModule.php index e54e5dcf13..3065935e33 100644 --- a/includes/resourceloader/ResourceLoaderUserTokensModule.php +++ b/includes/resourceloader/ResourceLoaderUserTokensModule.php @@ -32,7 +32,7 @@ class ResourceLoaderUserTokensModule extends ResourceLoaderModule { /** * Fetch the tokens for the current user. - * + * * @param $context ResourceLoaderContext: Context object * @return Array: List of tokens keyed by token type */ @@ -50,7 +50,7 @@ class ResourceLoaderUserTokensModule extends ResourceLoaderModule { * @return string */ public function getScript( ResourceLoaderContext $context ) { - return Xml::encodeJsCall( 'mw.user.tokens.set', + return Xml::encodeJsCall( 'mw.user.tokens.set', array( $this->contextUserTokens( $context ) ) ); } @@ -60,7 +60,10 @@ class ResourceLoaderUserTokensModule extends ResourceLoaderModule { public function getGroup() { return 'private'; } - + + /** + * @return array + */ public function getDependencies() { return array( 'mediawiki.user' ); } diff --git a/includes/resourceloader/ResourceLoaderWikiModule.php b/includes/resourceloader/ResourceLoaderWikiModule.php index 9a75f9be12..1643e259f0 100644 --- a/includes/resourceloader/ResourceLoaderWikiModule.php +++ b/includes/resourceloader/ResourceLoaderWikiModule.php @@ -24,35 +24,39 @@ defined( 'MEDIAWIKI' ) || die( 1 ); /** * Abstraction for resource loader modules which pull from wiki pages - * - * This can only be used for wiki pages in the MediaWiki and User namespaces, - * because of its dependence on the functionality of + * + * This can only be used for wiki pages in the MediaWiki and User namespaces, + * because of its dependence on the functionality of * Title::isValidCssJsSubpage. */ abstract class ResourceLoaderWikiModule extends ResourceLoaderModule { - + /* Protected Members */ # Origin is user-supplied code protected $origin = self::ORIGIN_USER_SITEWIDE; - + // In-object cache for title mtimes protected $titleMtimes = array(); - + /* Abstract Protected Methods */ - + + /** + * @abstract + * @param $context ResourceLoaderContext + */ abstract protected function getPages( ResourceLoaderContext $context ); - + /* Protected Methods */ - + /** * Get the Database object used in getTitleMTimes(). Defaults to the local slave DB * but subclasses may want to override this to return a remote DB object. - * + * * NOTE: This ONLY works for getTitleMTimes() and getModifiedTime(), NOT FOR ANYTHING ELSE. * In particular, it doesn't work for getting the content of JS and CSS pages. That functionality * will use the local DB irrespective of the return value of this method. - * + * * @return DatabaseBase */ protected function getDB() { @@ -77,7 +81,7 @@ abstract class ResourceLoaderWikiModule extends ResourceLoaderModule { } return $revision->getRawText(); } - + /* Methods */ /** @@ -112,7 +116,7 @@ abstract class ResourceLoaderWikiModule extends ResourceLoaderModule { */ public function getStyles( ResourceLoaderContext $context ) { global $wgScriptPath; - + $styles = array(); foreach ( $this->getPages( $context ) as $titleText => $options ) { if ( $options['type'] !== 'style' ) { @@ -121,7 +125,7 @@ abstract class ResourceLoaderWikiModule extends ResourceLoaderModule { $title = Title::newFromText( $titleText ); if ( !$title || $title->isRedirect() ) { continue; - } + } $media = isset( $options['media'] ) ? $options['media'] : 'all'; $style = $this->getContent( $title ); if ( strval( $style ) === '' ) { @@ -174,13 +178,13 @@ abstract class ResourceLoaderWikiModule extends ResourceLoaderModule { if ( isset( $this->titleMtimes[$hash] ) ) { return $this->titleMtimes[$hash]; } - + $this->titleMtimes[$hash] = array(); $batch = new LinkBatch; foreach ( $this->getPages( $context ) as $titleText => $options ) { $batch->addObj( Title::newFromText( $titleText ) ); } - + if ( !$batch->isEmpty() ) { $dbr = $this->getDB(); $res = $dbr->select( 'page', -- 2.20.1