From 94ba63be03795a37598e93617ff8130daedcc472 Mon Sep 17 00:00:00 2001 From: Timo Tijhof Date: Fri, 7 Mar 2014 17:50:57 +0100 Subject: [PATCH] doc: Clean up documentation in ResourceLoader.php Change-Id: I33e47e1bfb7dbff1304e56033c62fb80dfefdcf0 --- includes/resourceloader/ResourceLoader.php | 112 ++++++++++----------- 1 file changed, 54 insertions(+), 58 deletions(-) diff --git a/includes/resourceloader/ResourceLoader.php b/includes/resourceloader/ResourceLoader.php index 557c1f68e2..d51e06aa81 100644 --- a/includes/resourceloader/ResourceLoader.php +++ b/includes/resourceloader/ResourceLoader.php @@ -26,7 +26,7 @@ * Dynamic JavaScript and CSS resource loading system. * * Most of the documention is on the MediaWiki documentation wiki starting at: - * http://www.mediawiki.org/wiki/ResourceLoader + * https://www.mediawiki.org/wiki/ResourceLoader */ class ResourceLoader { @@ -53,7 +53,7 @@ class ResourceLoader { /* Protected Methods */ /** - * Loads information stored in the database about modules. + * Load information stored in the database about modules. * * This method grabs modules dependencies from the database and updates modules * objects. @@ -64,7 +64,7 @@ class ResourceLoader { * performance improvement. * * @param array $modules List of module names to preload information for - * @param $context ResourceLoaderContext: Context to load the information within + * @param ResourceLoaderContext $context Context to load the information within */ public function preloadModuleInfo( array $modules, ResourceLoaderContext $context ) { if ( !count( $modules ) ) { @@ -122,18 +122,19 @@ class ResourceLoader { } /** - * Runs JavaScript or CSS data through a filter, caching the filtered result for future calls. + * Run JavaScript or CSS data through a filter, caching the filtered result for future calls. * * Available filters are: - * - minify-js \see JavaScriptMinifier::minify - * - minify-css \see CSSMin::minify + * + * - minify-js \see JavaScriptMinifier::minify + * - minify-css \see CSSMin::minify * * If $data is empty, only contains whitespace or the filter was unknown, * $data is returned unmodified. * * @param string $filter Name of filter to run * @param string $data Text to filter, such as JavaScript or CSS text - * @return String: Filtered data, or a comment containing an error message + * @return string Filtered data, or a comment containing an error message */ protected function filter( $filter, $data ) { global $wgResourceLoaderMinifierStatementsOnOwnLine, $wgResourceLoaderMinifierMaxLineLength; @@ -193,7 +194,7 @@ class ResourceLoader { /* Methods */ /** - * Registers core modules and runs registration hooks. + * Register core modules and runs registration hooks. */ public function __construct() { global $IP, $wgResourceModules, $wgResourceLoaderSources, $wgLoadScript, $wgEnableJavaScriptTest; @@ -220,17 +221,17 @@ class ResourceLoader { } /** - * Registers a module with the ResourceLoader system. + * Register a module with the ResourceLoader system. * - * @param $name Mixed: Name of module as a string or List of name/object pairs as an array + * @param mixed $name Name of module as a string or List of name/object pairs as an array * @param array $info Module info array. For backwards compatibility with 1.17alpha, * this may also be a ResourceLoaderModule object. Optional when using * multiple-registration calling style. * @throws MWException: If a duplicate module registration is attempted * @throws MWException: If a module name contains illegal characters (pipes or commas) * @throws MWException: If something other than a ResourceLoaderModule is being registered - * @return Boolean: False if there were any errors, in which case one or more modules were not - * registered + * @return boolean False if there were any errors, in which case one or more modules were + * not registered */ public function register( $name, $info = null ) { wfProfileIn( __METHOD__ ); @@ -322,8 +323,8 @@ class ResourceLoader { * 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 array $properties source properties + * @param mixed $id Source ID (string), or array( id1 => props1, id2 => props2, ... ) + * @param array $properties Source properties * @throws MWException */ public function addSource( $id, $properties = null ) { @@ -354,9 +355,9 @@ class ResourceLoader { } /** - * Get a list of module names + * Get a list of module names. * - * @return Array: List of module names + * @return array List of module names */ public function getModuleNames() { return array_keys( $this->moduleInfos ); @@ -364,11 +365,12 @@ class ResourceLoader { /** * Get a list of test module names for one (or all) frameworks. + * * If the given framework id is unknkown, or if the in-object variable is not an array, * then it will return an empty array. * - * @param string $framework Optional. Get only the test module names for one - * particular framework. + * @param string $framework Get only the test module names for one + * particular framework (optional) * @return Array */ public function getTestModuleNames( $framework = 'all' ) { @@ -416,18 +418,18 @@ class ResourceLoader { } /** - * Get the list of sources + * Get the list of sources. * - * @return Array: array( id => array of properties, .. ) + * @return array Like array( id => array of properties, .. ) */ public function getSources() { return $this->sources; } /** - * Outputs a response to a resource load-request, including a content-type header. + * Output a response to a load request, including the content-type header. * - * @param $context ResourceLoaderContext: Context in which a response should be formed + * @param ResourceLoaderContext $context Context in which a response should be formed */ public function respond( ResourceLoaderContext $context ) { global $wgCacheEpoch, $wgUseFileCache; @@ -551,7 +553,7 @@ class ResourceLoader { /** * Send content type and last modified headers to the client. - * @param $context ResourceLoaderContext + * @param ResourceLoaderContext $context * @param string $mtime TS_MW timestamp to use for last-modified * @param bool $errors Whether there are commented-out errors in the response * @return void @@ -589,8 +591,11 @@ class ResourceLoader { } /** + * Respond with 304 Last Modified if appropiate. + * * If there's an If-Modified-Since header, respond with a 304 appropriately * and clear out the output buffer. If the client cache is too old then do nothing. + * * @param $context ResourceLoaderContext * @param string $mtime The TS_MW timestamp to check the header against * @return bool True if 304 header sent and output handled @@ -624,10 +629,10 @@ class ResourceLoader { } /** - * Send out code for a response from file cache if possible + * Send out code for a response from file cache if possible. * - * @param $fileCache ResourceFileCache: Cache object for this request URL - * @param $context ResourceLoaderContext: Context in which to generate a response + * @param ResourceFileCache $fileCache Cache object for this request URL + * @param ResourceLoaderContext $context Context in which to generate a response * @return bool If this found a cache file and handled the response */ protected function tryRespondFromFileCache( @@ -675,10 +680,11 @@ class ResourceLoader { } /** - * Generate a CSS or JS comment block. Only use this for public data, - * not error message details. + * Generate a CSS or JS comment block. * - * @param $text string + * Only use this for public data, not error message details. + * + * @param string $text * @return string */ public static function makeComment( $text ) { @@ -687,7 +693,7 @@ class ResourceLoader { } /** - * Handle exception display + * Handle exception display. * * @param Exception $e to be shown to the user * @return string sanitized text that can be returned to the user @@ -703,7 +709,7 @@ class ResourceLoader { } /** - * Generates code for a response + * Generate code for a response. * * @param $context ResourceLoaderContext Context in which to generate a response * @param array $modules List of module objects keyed by module name @@ -887,17 +893,15 @@ class ResourceLoader { /* Static Methods */ /** - * Returns JS code to call to mw.loader.implement for a module with - * given properties. + * Return JS code that calls mw.loader.implement with given module properties. * * @param string $name Module name - * @param $scripts Mixed: List of URLs to JavaScript files or String of JavaScript code - * @param $styles Mixed: Array of CSS strings keyed by media type, or an array of lists of URLs to - * CSS files keyed by media type - * @param $messages Mixed: List of messages associated with this module. May either be an - * associative array mapping message key to value, or a JSON-encoded message blob containing - * the same data, wrapped in an XmlJsCode object. - * + * @param mixed $scripts List of URLs to JavaScript files or String of JavaScript code + * @param mixed $styles Array of CSS strings keyed by media type, or an array of lists of URLs + * to CSS files keyed by media type + * @param mixed $messages List of messages associated with this module. May either be an + * associative array mapping message key to value, or a JSON-encoded message blob containing + * the same data, wrapped in an XmlJsCode object. * @throws MWException * @return string */ @@ -927,9 +931,8 @@ class ResourceLoader { /** * Returns JS code which, when called, will register a given list of messages. * - * @param $messages Mixed: Either an associative array mapping message key to value, or a - * JSON-encoded message blob containing the same data, wrapped in an XmlJsCode object. - * + * @param mixed $messages Either an associative array mapping message key to value, or a + * JSON-encoded message blob containing the same data, wrapped in an XmlJsCode object. * @return string */ public static function makeMessageSetScript( $messages ) { @@ -940,9 +943,8 @@ class ResourceLoader { * Combines an associative array mapping media type to CSS into a * single stylesheet with "@media" blocks. * - * @param array $stylePairs Array keyed by media type containing (arrays of) CSS strings. - * - * @return Array + * @param array $stylePairs Array keyed by media type containing (arrays of) CSS strings + * @return array */ private static function makeCombinedStyles( array $stylePairs ) { $out = array(); @@ -981,9 +983,8 @@ class ResourceLoader { * - ResourceLoader::makeLoaderStateScript( array( $name => $state, ... ) ): * Set the state of modules with the given names to the given states * - * @param $name string + * @param string $name * @param $state - * * @return string */ public static function makeLoaderStateScript( $name, $state = null ) { @@ -1001,12 +1002,11 @@ class ResourceLoader { * and $group as supplied. * * @param string $name Module name - * @param $version Integer: Module version number as a timestamp + * @param int $version Module version number as a timestamp * @param array $dependencies List of module names on which this module depends * @param string $group Group which the module is in. * @param string $source Source of the module, or 'local' if not foreign. * @param string $script JavaScript code - * * @return string */ public static function makeCustomLoaderScript( $name, $version, $dependencies, $group, $source, $script ) { @@ -1034,11 +1034,10 @@ class ResourceLoader { * Registers modules with the given names and parameters. * * @param string $name Module name - * @param $version Integer: Module version number as a timestamp + * @param int $version Module version number as a timestamp * @param array $dependencies List of module names on which this module depends - * @param string $group group which the module is in. - * @param string $source source of the module, or 'local' if not foreign - * + * @param string $group Group which the module is in + * @param string $source Source of the module, or 'local' if not foreign * @return string */ public static function makeLoaderRegisterScript( $name, $version = null, @@ -1065,7 +1064,6 @@ class ResourceLoader { * * @param string $id source ID * @param array $properties source properties (see addSource()) - * * @return string */ public static function makeLoaderSourcesScript( $id, $properties = null ) { @@ -1081,7 +1079,6 @@ class ResourceLoader { * present. * * @param string $script JavaScript code - * * @return string */ public static function makeLoaderConditionalScript( $script ) { @@ -1093,7 +1090,6 @@ class ResourceLoader { * the given value. * * @param array $configuration List of configuration values keyed by variable name - * * @return string */ public static function makeConfigSetScript( array $configuration ) { @@ -1105,7 +1101,7 @@ class ResourceLoader { * * For example, array( 'foo.bar', 'foo.baz', 'bar.baz', 'bar.quux' ) * becomes 'foo.bar,baz|bar.baz,quux' - * @param array $modules of module names (strings) + * @param array $modules List of module names (strings) * @return string Packed query string */ public static function makePackedModulesString( $modules ) { -- 2.20.1