From c519873cdccf1573599029d85c1437c562bc7c6c Mon Sep 17 00:00:00 2001 From: Trevor Parscal Date: Fri, 5 Nov 2010 18:33:50 +0000 Subject: [PATCH] Fixed Doxygen incompatible JSDoc style comments (bad Trevor!) as per some comments on r75036. --- includes/resourceloader/ResourceLoader.php | 80 ++++++------- .../ResourceLoaderFileModule.php | 112 +++++++++--------- .../resourceloader/ResourceLoaderModule.php | 40 +++---- .../ResourceLoaderSiteModule.php | 4 +- .../ResourceLoaderStartUpModule.php | 1 + .../ResourceLoaderUserOptionsModule.php | 4 +- 6 files changed, 120 insertions(+), 121 deletions(-) diff --git a/includes/resourceloader/ResourceLoader.php b/includes/resourceloader/ResourceLoader.php index 3ce7148f29..770c62868e 100644 --- a/includes/resourceloader/ResourceLoader.php +++ b/includes/resourceloader/ResourceLoader.php @@ -30,7 +30,7 @@ class ResourceLoader { /* Protected Static Members */ - /** @var {array} List of module name/ResourceLoaderModule object pairs */ + /** Array: List of module name/ResourceLoaderModule object pairs */ protected $modules = array(); /* Protected Methods */ @@ -46,8 +46,8 @@ class ResourceLoader { * requests its own information. This sacrifice of modularity yields a profound * performance improvement. * - * @param $modules Array: list of module names to preload information for - * @param $context ResourceLoaderContext: context to load the information within + * @param $modules Array: List of module names to preload information for + * @param $context ResourceLoaderContext: Context to load the information within */ protected function preloadModuleInfo( array $modules, ResourceLoaderContext $context ) { if ( !count( $modules ) ) { @@ -114,9 +114,9 @@ class ResourceLoader { * If $data is empty, only contains whitespace or the filter was unknown, * $data is returned unmodified. * - * @param $filter String: name of filter to run - * @param $data String: text to filter, such as JavaScript or CSS text - * @return String: filtered data + * @param $filter String: Name of filter to run + * @param $data String: Text to filter, such as JavaScript or CSS text + * @return String: Filtered data */ protected function filter( $filter, $data ) { global $wgMemc; @@ -187,14 +187,13 @@ class ResourceLoader { /** * Registers a module with the ResourceLoader system. * - * @param $name Mixed: string of name of module or array of name/object pairs - * @param $object ResourceLoaderModule: module object (optional when using - * multiple-registration calling style) - * @throws MWException If a duplicate module registration is attempted - * @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 + * @param $name Mixed: Name of module as a string or List of name/object pairs as an array + * @param $object ResourceLoaderModule: Module object (optional when using + * multiple-registration calling style) + * @throws MWException: If a duplicate module registration is attempted + * @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 */ public function register( $name, ResourceLoaderModule $object = null ) { @@ -236,7 +235,7 @@ class ResourceLoader { /** * Gets a map of all modules and their options * - * @return Array: array( modulename => ResourceLoaderModule ) + * @return Array: List of modules keyed by module name */ public function getModules() { return $this->modules; @@ -245,7 +244,7 @@ class ResourceLoader { /** * Get the ResourceLoaderModule object for a given module name. * - * @param $name String: module name + * @param $name String: Module name * @return Mixed: ResourceLoaderModule if module has been registered, null otherwise */ public function getModule( $name ) { @@ -255,7 +254,7 @@ class ResourceLoader { /** * Outputs a response to a resource load-request, including a content-type header. * - * @param $context ResourceLoaderContext: context in which a response should be formed + * @param $context ResourceLoaderContext: Context in which a response should be formed */ public function respond( ResourceLoaderContext $context ) { global $wgResourceLoaderMaxage, $wgCacheEpoch; @@ -345,10 +344,10 @@ class ResourceLoader { /** * Generates code for a response * - * @param $context ResourceLoaderContext: context in which to generate a response - * @param $modules Array: list of module objects keyed by module name - * @param $missing Array: list of unavailable modules (optional) - * @return String: response data + * @param $context ResourceLoaderContext: Context in which to generate a response + * @param $modules Array: List of module objects keyed by module name + * @param $missing Array: List of unavailable modules (optional) + * @return String: Response data */ public function makeModuleResponse( ResourceLoaderContext $context, array $modules, $missing = array() ) @@ -447,12 +446,12 @@ class ResourceLoader { * given properties. * * @param $name Module name - * @param $scripts Array of JavaScript code snippets to be executed after the + * @param $scripts Array: List of JavaScript code snippets to be executed after the * module is loaded - * @param $styles Associative array mapping media type to associated CSS string - * @param $messages 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 $styles Array: List of CSS strings 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. */ public static function makeLoaderImplementScript( $name, $scripts, $styles, $messages ) { if ( is_array( $scripts ) ) { @@ -471,9 +470,8 @@ class ResourceLoader { /** * Returns JS code which, when called, will register a given list of messages. * - * @param $messages 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 $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. */ public static function makeMessageSetScript( $messages ) { return Xml::encodeJsCall( 'mediaWiki.messages.set', array( (object)$messages ) ); @@ -483,7 +481,7 @@ class ResourceLoader { * Combines an associative array mapping media type to CSS into a * single stylesheet with @media blocks. * - * @param $styles Array of CSS strings + * @param $styles Array: List of CSS strings keyed by media type */ public static function makeCombinedStyles( array $styles ) { $out = ''; @@ -517,11 +515,11 @@ class ResourceLoader { * which will have values corresponding to $name, $version, $dependencies * and $group as supplied. * - * @param $name The module name - * @param $version The module version string - * @param $dependencies Array of module names on which this module depends - * @param $group The group which the module is in. - * @param $script The JS loader script + * @param $name String: Module name + * @param $version Integer: Module version number as a timestamp + * @param $dependencies Array: List of module names on which this module depends + * @param $group String: Group which the module is in. + * @param $script String: JavaScript code */ public static function makeCustomLoaderScript( $name, $version, $dependencies, $group, $script ) { $script = str_replace( "\n", "\n\t", trim( $script ) ); @@ -547,10 +545,10 @@ class ResourceLoader { * ) ): * Registers modules with the given names and parameters. * - * @param $name The module name - * @param $version The module version string - * @param $dependencies Array of module names on which this module depends - * @param $group The group which the module is in. + * @param $name String: Module name + * @param $version Integer: Module version number as a timestamp + * @param $dependencies Array: List of module names on which this module depends + * @param $group String: group which the module is in. */ public static function makeLoaderRegisterScript( $name, $version = null, $dependencies = null, $group = null ) @@ -568,7 +566,7 @@ class ResourceLoader { * Returns JS code which runs given JS code if the client-side framework is * present. * - * @param $script JS code to run + * @param $script String: JavaScript code */ public static function makeLoaderConditionalScript( $script ) { $script = str_replace( "\n", "\n\t", trim( $script ) ); @@ -579,7 +577,7 @@ class ResourceLoader { * Returns JS code which will set the MediaWiki configuration array to * the given value. * - * @param $configuration Associative array of configuration parameters + * @param $configuration Array: List of configuration values keyed by variable name */ public static function makeConfigSetScript( array $configuration ) { return Xml::encodeJsCall( 'mediaWiki.config.set', array( $configuration ) ); diff --git a/includes/resourceloader/ResourceLoaderFileModule.php b/includes/resourceloader/ResourceLoaderFileModule.php index ae87a48713..c03391c044 100644 --- a/includes/resourceloader/ResourceLoaderFileModule.php +++ b/includes/resourceloader/ResourceLoaderFileModule.php @@ -27,67 +27,67 @@ class ResourceLoaderFileModule extends ResourceLoaderModule { /* Protected Members */ - /** @var {string} Local base path, see __construct() */ + /** String: Local base path, see __construct() */ protected $localBasePath = ''; - /** @var {string} Remote base path, see __construct() */ + /** String: Remote base path, see __construct() */ protected $remoteBasePath = ''; /** - * @var {array} List of paths to JavaScript files to always include - * @format array( [file-path], [file-path], ... ) + * Array: List of paths to JavaScript files to always include + * @example array( [file-path], [file-path], ... ) */ protected $scripts = array(); /** - * @var {array} List of JavaScript files to include when using a specific language - * @format array( [language-code] => array( [file-path], [file-path], ... ), ... ) + * Array: List of JavaScript files to include when using a specific language + * @example array( [language-code] => array( [file-path], [file-path], ... ), ... ) */ protected $languageScripts = array(); /** - * @var {array} List of JavaScript files to include when using a specific skin - * @format array( [skin-name] => array( [file-path], [file-path], ... ), ... ) + * Array: List of JavaScript files to include when using a specific skin + * @example array( [skin-name] => array( [file-path], [file-path], ... ), ... ) */ protected $skinScripts = array(); /** - * @var {array} List of paths to JavaScript files to include in debug mode - * @format array( [skin-name] => array( [file-path], [file-path], ... ), ... ) + * Array: List of paths to JavaScript files to include in debug mode + * @example array( [skin-name] => array( [file-path], [file-path], ... ), ... ) */ protected $debugScripts = array(); /** - * @var {array} List of paths to JavaScript files to include in the startup module - * @format array( [file-path], [file-path], ... ) + * Array: List of paths to JavaScript files to include in the startup module + * @example array( [file-path], [file-path], ... ) */ protected $loaderScripts = array(); /** - * @var {array} List of paths to CSS files to always include - * @format array( [file-path], [file-path], ... ) + * Array: List of paths to CSS files to always include + * @example array( [file-path], [file-path], ... ) */ protected $styles = array(); /** - * @var {array} List of paths to CSS files to include when using specific skins - * @format array( [file-path], [file-path], ... ) + * Array: List of paths to CSS files to include when using specific skins + * @example array( [file-path], [file-path], ... ) */ protected $skinStyles = array(); /** - * @var {array} List of modules this module depends on - * @format array( [file-path], [file-path], ... ) + * Array: List of modules this module depends on + * @example array( [file-path], [file-path], ... ) */ protected $dependencies = array(); /** - * @var {array} List of message keys used by this module - * @format array( [message-key], [message-key], ... ) + * Array: List of message keys used by this module + * @example array( [message-key], [message-key], ... ) */ protected $messages = array(); - /** @var {string} Name of group to load this module in */ + /** String: Name of group to load this module in */ protected $group; - /** @var {boolean} Link to raw files in debug mode */ + /** Boolean: Link to raw files in debug mode */ protected $debugRaw = true; /** - * @var {array} Cache for mtime - * @format array( [hash] => [mtime], [hash] => [mtime], ... ) + * Array: Cache for mtime + * @example array( [hash] => [mtime], [hash] => [mtime], ... ) */ protected $modifiedTime = array(); /** - * @var {array} Place where readStyleFile() tracks file dependencies - * @format array( [file-path], [file-path], ... ) + * Array: Place where readStyleFile() tracks file dependencies + * @example array( [file-path], [file-path], ... ) */ protected $localFileRefs = array(); @@ -96,14 +96,14 @@ class ResourceLoaderFileModule extends ResourceLoaderModule { /** * Constructs a new module from an options array. * - * @param {array} $options Options array. If not given or empty, an empty - * module will be constructed - * @param {string} $localBasePath base path to prepend to all local paths - * in $options. Defaults to $IP - * @param {string} $remoteBasePath base path to prepend to all remote paths - * in $options. Defaults to $wgScriptPath + * @param $options Array: List of options; if not given or empty, an empty module will be + * constructed + * @param $localBasePath String: Base path to prepend to all local paths in $options. Defaults + * to $IP + * @param $remoteBasePath String: Base path to prepend to all remote paths in $options. Defaults + * to $wgScriptPath * - * @format $options + * @example $options * array( * // Scripts to always include * 'scripts' => [file path string or array of file path strings], @@ -188,8 +188,8 @@ class ResourceLoaderFileModule extends ResourceLoaderModule { /** * Gets all scripts for a given context concatenated together. * - * @param {ResourceLoaderContext} $context Context in which to generate script - * @return {string} JavaScript code for $context + * @param $context ResourceLoaderContext: Context in which to generate script + * @return String: JavaScript code for $context */ public function getScript( ResourceLoaderContext $context ) { global $wgServer; @@ -216,7 +216,7 @@ class ResourceLoaderFileModule extends ResourceLoaderModule { /** * Gets loader script. * - * @return {string} JavaScript code to be added to startup module + * @return String: JavaScript code to be added to startup module */ public function getLoaderScript() { if ( count( $this->loaderScripts ) == 0 ) { @@ -228,8 +228,8 @@ class ResourceLoaderFileModule extends ResourceLoaderModule { /** * Gets all styles for a given context concatenated together. * - * @param {ResourceLoaderContext} $context Context in which to generate styles - * @return {string} CSS code for $context + * @param $context ResourceLoaderContext: Context in which to generate styles + * @return String: CSS code for $context */ public function getStyles( ResourceLoaderContext $context ) { // Merge general styles and skin specific styles, retaining media type collation @@ -263,7 +263,7 @@ class ResourceLoaderFileModule extends ResourceLoaderModule { /** * Gets list of message keys used by this module. * - * @return {array} List of message keys + * @return Array: List of message keys */ public function getMessages() { return $this->messages; @@ -272,7 +272,7 @@ class ResourceLoaderFileModule extends ResourceLoaderModule { /** * Gets the name of the group this module should be loaded in. * - * @return {string} Group name + * @return String: Group name */ public function getGroup() { return $this->group; @@ -281,7 +281,7 @@ class ResourceLoaderFileModule extends ResourceLoaderModule { /** * Gets list of names of modules this module depends on. * - * @return {array} List of module names + * @return Array: List of module names */ public function getDependencies() { return $this->dependencies; @@ -296,10 +296,10 @@ class ResourceLoaderFileModule extends ResourceLoaderModule { * calculations on files relevant to the given language, skin and debug * mode. * - * @param {ResourceLoaderContext} $context Context in which to calculate + * @param $context ResourceLoaderContext: Context in which to calculate * the modified time - * @return {integer} UNIX timestamp - * @see {ResourceLoaderModule::getFileDependencies} + * @return Integer: UNIX timestamp + * @see ResourceLoaderModule::getFileDependencies */ public function getModifiedTime( ResourceLoaderContext $context ) { if ( isset( $this->modifiedTime[$context->getHash()] ) ) { @@ -365,9 +365,9 @@ class ResourceLoaderFileModule extends ResourceLoaderModule { /** * Collates file paths by option (where provided). * - * @param {array} $list List of file paths in any combination of index/path + * @param $list Array: List of file paths in any combination of index/path * or path/options pairs - * @return {array} List of file paths, collated by $option + * @return Array: List of file paths, collated by $option */ protected static function collateFilePathListByOption( array $list, $option, $default ) { $collatedFiles = array(); @@ -393,10 +393,10 @@ class ResourceLoaderFileModule extends ResourceLoaderModule { /** * Gets a list of element that match a key, optionally using a fallback key. * - * @param {array} $list List of lists to select from - * @param {string} $key Key to look for in $map - * @param {string} $fallback Key to look for in $list if $key doesn't exist - * @return {array} List of elements from $map which matched $key or $fallback, + * @param $list Array: List of lists to select from + * @param $key String: Key to look for in $map + * @param $fallback String: Key to look for in $list if $key doesn't exist + * @return Array: List of elements from $map which matched $key or $fallback, * or an empty list in case of no match */ protected static function tryForKey( array $list, $key, $fallback = null ) { @@ -414,8 +414,8 @@ class ResourceLoaderFileModule extends ResourceLoaderModule { /** * Gets the contents of a list of JavaScript files. * - * @param {array} $scripts List of file paths to scripts to read, remap and concetenate - * @return {string} Concatenated and remapped JavaScript data from $scripts + * @param $scripts Array: List of file paths to scripts to read, remap and concetenate + * @return String: Concatenated and remapped JavaScript data from $scripts */ protected function readScriptFiles( array $scripts ) { if ( empty( $scripts ) ) { @@ -436,8 +436,8 @@ class ResourceLoaderFileModule extends ResourceLoaderModule { /** * Gets the contents of a list of CSS files. * - * @param {array} $styles List of file paths to styles to read, remap and concetenate - * @return {array} List of concatenated and remapped CSS data from $styles, + * @param $styles Array: List of file paths to styles to read, remap and concetenate + * @return Array: List of concatenated and remapped CSS data from $styles, * keyed by media type */ protected function readStyleFiles( array $styles ) { @@ -458,8 +458,8 @@ class ResourceLoaderFileModule extends ResourceLoaderModule { * * This method can be used as a callback for array_map() * - * @param {string} $path File path of script file to read - * @return {string} CSS data in script file + * @param $path String: File path of script file to read + * @return String: CSS data in script file */ protected function readStyleFile( $path ) { $localPath = $this->getLocalPath( $path ); diff --git a/includes/resourceloader/ResourceLoaderModule.php b/includes/resourceloader/ResourceLoaderModule.php index 797fca986a..b60ae7b4f2 100644 --- a/includes/resourceloader/ResourceLoaderModule.php +++ b/includes/resourceloader/ResourceLoaderModule.php @@ -40,7 +40,7 @@ abstract class ResourceLoaderModule { * Get this module's name. This is set when the module is registered * with ResourceLoader::register() * - * @return Mixed: name (string) or null if no name was set + * @return Mixed: Name (string) or null if no name was set */ public function getName() { return $this->name; @@ -50,7 +50,7 @@ abstract class ResourceLoaderModule { * Set this module's name. This is called by ResourceLodaer::register() * when registering the module. Other code should not call this. * - * @param $name String: name + * @param $name String: Name */ public function setName( $name ) { $this->name = $name; @@ -67,8 +67,8 @@ abstract class ResourceLoaderModule { * Get all JS for this module for a given language and skin. * Includes all relevant JS except loader scripts. * - * @param $context ResourceLoaderContext object - * @return String: JS + * @param $context ResourceLoaderContext: Context object + * @return String: JavaScript code */ public function getScript( ResourceLoaderContext $context ) { // Stub, override expected @@ -78,8 +78,8 @@ abstract class ResourceLoaderModule { /** * Get all CSS for this module for a given skin. * - * @param $context ResourceLoaderContext object - * @return array: strings of CSS keyed by media type + * @param $context ResourceLoaderContext: Context object + * @return Array: List of CSS strings keyed by media type */ public function getStyles( ResourceLoaderContext $context ) { // Stub, override expected @@ -91,7 +91,7 @@ abstract class ResourceLoaderModule { * * To get a JSON blob with messages, use MessageBlobStore::get() * - * @return array of message keys. Keys may occur more than once + * @return Array: List of message keys. Keys may occur more than once */ public function getMessages() { // Stub, override expected @@ -101,7 +101,7 @@ abstract class ResourceLoaderModule { /** * Get the group this module is in. * - * @return string of group name + * @return String: Group name */ public function getGroup() { // Stub, override expected @@ -111,7 +111,7 @@ abstract class ResourceLoaderModule { /** * Get the loader JS for this module, if set. * - * @return Mixed: loader JS (string) or false if no custom loader set + * @return Mixed: JavaScript loader code as a string or boolean false if no custom loader set */ public function getLoaderScript() { // Stub, override expected @@ -131,7 +131,7 @@ abstract class ResourceLoaderModule { * * To add dependencies dynamically on the client side, use a custom * loader script, see getLoaderScript() - * @return Array of module names (strings) + * @return Array: List of module names as strings */ public function getDependencies() { // Stub, override expected @@ -142,8 +142,8 @@ abstract class ResourceLoaderModule { * Get the files this module depends on indirectly for a given skin. * Currently these are only image files referenced by the module's CSS. * - * @param $skin String: skin name - * @return array of files + * @param $skin String: Skin name + * @return Array: List of files */ public function getFileDependencies( $skin ) { // Try in-object cache first @@ -168,8 +168,8 @@ abstract class ResourceLoaderModule { /** * Set preloaded file dependency information. Used so we can load this * information for all modules at once. - * @param $skin string Skin name - * @param $deps array Array of file names + * @param $skin String: Skin name + * @param $deps Array: Array of file names */ public function setFileDependencies( $skin, $deps ) { $this->fileDeps[$skin] = $deps; @@ -178,8 +178,8 @@ abstract class ResourceLoaderModule { /** * Get the last modification timestamp of the message blob for this * module in a given language. - * @param $lang string Language code - * @return int UNIX timestamp, or 0 if no blob found + * @param $lang String: Language code + * @return Integer: UNIX timestamp, or 0 if no blob found */ public function getMsgBlobMtime( $lang ) { if ( !count( $this->getMessages() ) ) @@ -198,8 +198,8 @@ abstract class ResourceLoaderModule { /** * Set a preloaded message blob last modification timestamp. Used so we * can load this information for all modules at once. - * @param $lang string Language code - * @param $mtime int UNIX timestamp or 0 if there is no such blob + * @param $lang String: Language code + * @param $mtime Integer: UNIX timestamp or 0 if there is no such blob */ public function setMsgBlobMtime( $lang, $mtime ) { $this->msgBlobMtime[$lang] = $mtime; @@ -214,8 +214,8 @@ abstract class ResourceLoaderModule { * timestamps. Whenever anything happens that changes the module's * contents for these parameters, the mtime should increase. * - * @param $context ResourceLoaderContext object - * @return int UNIX timestamp + * @param $context ResourceLoaderContext: Context object + * @return Integer: UNIX timestamp */ public function getModifiedTime( ResourceLoaderContext $context ) { // 0 would mean now diff --git a/includes/resourceloader/ResourceLoaderSiteModule.php b/includes/resourceloader/ResourceLoaderSiteModule.php index 44e018a0a9..2336acbf3a 100644 --- a/includes/resourceloader/ResourceLoaderSiteModule.php +++ b/includes/resourceloader/ResourceLoaderSiteModule.php @@ -30,7 +30,7 @@ class ResourceLoaderSiteModule extends ResourceLoaderWikiModule { /** * Gets list of pages used by this module * - * @return {array} List of pages + * @return Array: List of pages */ protected function getPages( ResourceLoaderContext $context ) { global $wgHandheldStyle; @@ -56,7 +56,7 @@ class ResourceLoaderSiteModule extends ResourceLoaderWikiModule { /** * Gets group name * - * @return {string} Name of group + * @return String: Name of group */ public function getGroup() { return 'site'; diff --git a/includes/resourceloader/ResourceLoaderStartUpModule.php b/includes/resourceloader/ResourceLoaderStartUpModule.php index 4e7f0b9214..718831e5d4 100644 --- a/includes/resourceloader/ResourceLoaderStartUpModule.php +++ b/includes/resourceloader/ResourceLoaderStartUpModule.php @@ -21,6 +21,7 @@ */ class ResourceLoaderStartUpModule extends ResourceLoaderModule { + /* Protected Members */ protected $modifiedTime = array(); diff --git a/includes/resourceloader/ResourceLoaderUserOptionsModule.php b/includes/resourceloader/ResourceLoaderUserOptionsModule.php index f32d08938a..17352e348e 100644 --- a/includes/resourceloader/ResourceLoaderUserOptionsModule.php +++ b/includes/resourceloader/ResourceLoaderUserOptionsModule.php @@ -50,8 +50,8 @@ class ResourceLoaderUserOptionsModule extends ResourceLoaderModule { * Fetch the context's user options, or if it doesn't match current user, * the default options. * - * @param $context ResourceLoaderContext - * @return array + * @param $context ResourceLoaderContext: Context object + * @return Array: List of user options keyed by option name */ protected function contextUserOptions( ResourceLoaderContext $context ) { global $wgUser; -- 2.20.1