From 296f3d3f4f4bdd530264b5c67498f573439ef58b Mon Sep 17 00:00:00 2001 From: Sam Reed Date: Sat, 28 May 2011 18:59:42 +0000 Subject: [PATCH] And even more documentation --- includes/ForkController.php | 2 ++ includes/GlobalFunctions.php | 1 + includes/ImageGallery.php | 2 ++ includes/Init.php | 20 ++++++++++- includes/Linker.php | 7 +++- includes/LocalisationCache.php | 2 ++ includes/filerepo/FSRepo.php | 16 +++++++++ includes/filerepo/LocalFile.php | 18 ++++++++-- includes/filerepo/LocalRepo.php | 5 +++ includes/filerepo/RepoGroup.php | 9 +++-- includes/filerepo/UnregisteredLocalFile.php | 16 +++++++-- includes/installer/OracleUpdater.php | 2 ++ includes/installer/SqliteInstaller.php | 39 +++++++++++++++++++-- includes/job/DoubleRedirectJob.php | 3 ++ includes/job/JobQueue.php | 4 +++ includes/media/BMP.php | 23 ++++++++++-- includes/media/BitmapMetadataHandler.php | 12 ++++--- includes/media/Generic.php | 13 +++++++ includes/media/MediaTransformOutput.php | 15 ++++++-- includes/objectcache/DBABagOStuff.php | 4 ++- includes/objectcache/ObjectCache.php | 2 ++ includes/objectcache/SqlBagOStuff.php | 2 ++ includes/parser/CoreTagHooks.php | 12 +++---- includes/parser/ParserCache.php | 5 +++ 24 files changed, 206 insertions(+), 28 deletions(-) diff --git a/includes/ForkController.php b/includes/ForkController.php index 1cd49e76b5..d87dfb1e72 100644 --- a/includes/ForkController.php +++ b/includes/ForkController.php @@ -124,6 +124,8 @@ class ForkController { /** * Fork a number of worker processes. + * + * return string */ protected function forkWorkers( $numProcs ) { $this->prepareEnvironment(); diff --git a/includes/GlobalFunctions.php b/includes/GlobalFunctions.php index a664551109..f91505c287 100644 --- a/includes/GlobalFunctions.php +++ b/includes/GlobalFunctions.php @@ -85,6 +85,7 @@ if ( !function_exists( 'istainted' ) ) { function wfArrayDiff2( $a, $b ) { return array_udiff( $a, $b, 'wfArrayDiff2_cmp' ); } + function wfArrayDiff2_cmp( $a, $b ) { if ( !is_array( $a ) ) { return strcmp( $a, $b ); diff --git a/includes/ImageGallery.php b/includes/ImageGallery.php index cc561b4bd6..d3773007a6 100644 --- a/includes/ImageGallery.php +++ b/includes/ImageGallery.php @@ -58,6 +58,8 @@ class ImageGallery { /** * Register a parser object + * + * @param $parser Parser */ function setParser( $parser ) { $this->mParser = $parser; diff --git a/includes/Init.php b/includes/Init.php index 7f1449fb54..40a9e3093d 100644 --- a/includes/Init.php +++ b/includes/Init.php @@ -25,6 +25,8 @@ class MWInit { /** * Returns true if we are running under HipHop, whether in compiled or * interpreted mode. + * + * @return bool */ static function isHipHop() { return function_exists( 'hphp_thread_set_warmup_enabled' ); @@ -33,7 +35,11 @@ class MWInit { /** * Get a fully-qualified path for a source file relative to $IP. Including * such a path under HipHop will force the file to be interpreted. This is - * useful for configuration files. + * useful for configuration files. + * + * @param $file string + * + * @return string */ static function interpretedPath( $file ) { global $IP; @@ -46,6 +52,10 @@ class MWInit { * it will converted to a fully qualified path. It is necessary to use a * path which is relative to $IP in order to make HipHop use its compiled * code. + * + * @param $file string + * + * @return string */ static function compiledPath( $file ) { global $IP; @@ -68,6 +78,10 @@ class MWInit { * "volatile", which means (as of March 2011) that the class is broken and * can't be used at all. So don't do that. See * https://github.com/facebook/hiphop-php/issues/314 + * + * @param $class string + * + * @return bool */ static function classExists( $class ) { try { @@ -81,6 +95,10 @@ class MWInit { /** * Determine whether a function exists, using a method which works under * HipHop. + * + * @param $function string + * + * @return bool */ static function functionExists( $function ) { try { diff --git a/includes/Linker.php b/includes/Linker.php index 092fff60f4..2c62389ebb 100644 --- a/includes/Linker.php +++ b/includes/Linker.php @@ -82,6 +82,11 @@ class Linker { /** * Common code for getLinkAttributesX functions + * + * @param $title string + * @param $class string + * + * @return string */ private static function getLinkAttributesInternal( $title, $class ) { $title = htmlspecialchars( $title ); @@ -143,7 +148,7 @@ class Linker { * @param $query array The query string to append to the URL * you're linking to, in key => value array form. Query keys and values * will be URL-encoded. - * @param $options mixed String or array of strings: + * @param $options string|array String or array of strings: * 'known': Page is known to exist, so don't check if it does. * 'broken': Page is known not to exist, so don't check if it does. * 'noclasses': Don't add any classes automatically (includes "new", diff --git a/includes/LocalisationCache.php b/includes/LocalisationCache.php index 36867c8f8b..aac44337ff 100644 --- a/includes/LocalisationCache.php +++ b/includes/LocalisationCache.php @@ -137,6 +137,8 @@ class LocalisationCache { * Constructor. * For constructor parameters, see the documentation in DefaultSettings.php * for $wgLocalisationCacheConf. + * + * @param $conf Array */ function __construct( $conf ) { global $wgCacheDirectory; diff --git a/includes/filerepo/FSRepo.php b/includes/filerepo/FSRepo.php index f30e0affec..5739fbebf7 100644 --- a/includes/filerepo/FSRepo.php +++ b/includes/filerepo/FSRepo.php @@ -65,6 +65,10 @@ class FSRepo extends FileRepo { /** * Get the local directory corresponding to one of the three basic zones + * + * @param $zone string + * + * @return string */ function getZonePath( $zone ) { switch ( $zone ) { @@ -83,6 +87,10 @@ class FSRepo extends FileRepo { /** * @see FileRepo::getZoneUrl() + * + * @param $zone string + * + * @return url */ function getZoneUrl( $zone ) { switch ( $zone ) { @@ -103,6 +111,10 @@ class FSRepo extends FileRepo { * Get a URL referring to this repository, with the private mwrepo protocol. * The suffix, if supplied, is considered to be unencoded, and will be * URL-encoded before being returned. + * + * @param $suffix string + * + * @return string */ function getVirtualUrl( $suffix = false ) { $path = 'mwrepo://' . $this->name; @@ -114,6 +126,10 @@ class FSRepo extends FileRepo { /** * Get the local path corresponding to a virtual URL + * + * @param $url string + * + * @return string */ function resolveVirtualUrl( $url ) { if ( substr( $url, 0, 9 ) != 'mwrepo://' ) { diff --git a/includes/filerepo/LocalFile.php b/includes/filerepo/LocalFile.php index f86c5dd26f..15b419120e 100644 --- a/includes/filerepo/LocalFile.php +++ b/includes/filerepo/LocalFile.php @@ -63,6 +63,12 @@ class LocalFile extends File { * Do not call this except from inside a repo class. * * Note: $unused param is only here to avoid an E_STRICT + * + * @param $title + * @param $repo + * @param $unused + * + * @return LocalFile */ static function newFromTitle( $title, $repo, $unused = null ) { return new self( $title, $repo ); @@ -71,6 +77,11 @@ class LocalFile extends File { /** * Create a LocalFile from a title * Do not call this except from inside a repo class. + * + * @param $row + * @param $repo + * + * @return LocalFile */ static function newFromRow( $row, $repo ) { $title = Title::makeTitle( NS_FILE, $row->img_name ); @@ -83,9 +94,12 @@ class LocalFile extends File { /** * Create a LocalFile from a SHA-1 key * Do not call this except from inside a repo class. - * @param $sha1 + * + * @param $sha1 string * @param $repo LocalRepo - * @param $timestamp + * @param $timestamp string + * + * @return LocalFile */ static function newFromKey( $sha1, $repo, $timestamp = false ) { $conds = array( 'img_sha1' => $sha1 ); diff --git a/includes/filerepo/LocalRepo.php b/includes/filerepo/LocalRepo.php index 26651e6aba..34d07ef600 100644 --- a/includes/filerepo/LocalRepo.php +++ b/includes/filerepo/LocalRepo.php @@ -35,6 +35,11 @@ class LocalRepo extends FSRepo { } } + /** + * @param $title + * @param $archiveName + * @return OldLocalFile + */ function newFromArchiveName( $title, $archiveName ) { return OldLocalFile::newFromArchiveName( $title, $this, $archiveName ); } diff --git a/includes/filerepo/RepoGroup.php b/includes/filerepo/RepoGroup.php index 2d0b1ac84b..59407cf2e8 100644 --- a/includes/filerepo/RepoGroup.php +++ b/includes/filerepo/RepoGroup.php @@ -26,6 +26,9 @@ class RepoGroup { var $localInfo, $foreignInfo; var $cache; + /** + * @var RepoGroup + */ protected static $instance; const MAX_CACHE_SIZE = 1000; @@ -53,6 +56,8 @@ class RepoGroup { /** * Set the singleton instance to a given object + * + * @param $instance RepoGroup */ static function setSingleton( $instance ) { self::$instance = $instance; @@ -77,8 +82,8 @@ class RepoGroup { * Search repositories for an image. * You can also use wfFindFile() to do this. * - * @param $title Mixed: Title object or string - * @param $options Associative array of options: + * @param $title Title|string Title object or string + * @param $options array Associative array of options: * time: requested time for an archived image, or false for the * current version. An image object will be returned which was * created at the specified time. diff --git a/includes/filerepo/UnregisteredLocalFile.php b/includes/filerepo/UnregisteredLocalFile.php index 71001bd325..2df9a9b5d2 100644 --- a/includes/filerepo/UnregisteredLocalFile.php +++ b/includes/filerepo/UnregisteredLocalFile.php @@ -26,20 +26,30 @@ class UnregisteredLocalFile extends File { */ var $handler; + /** + * @param $path + * @param $mime + * @return UnregisteredLocalFile + */ static function newFromPath( $path, $mime ) { return new UnregisteredLocalFile( false, false, $path, $mime ); } + /** + * @param $title + * @param $repo + * @return UnregisteredLocalFile + */ static function newFromTitle( $title, $repo ) { return new UnregisteredLocalFile( $title, $repo, false, false ); } /** * @throws MWException - * @param bool $title + * @param $title string * @param $repo FSRepo - * @param bool $path - * @param bool $mime + * @param $path string + * @param $mime string */ function __construct( $title = false, $repo = false, $path = false, $mime = false ) { if ( !( $title && $repo ) && !$path ) { diff --git a/includes/installer/OracleUpdater.php b/includes/installer/OracleUpdater.php index fc5d8c2965..c34369ff19 100644 --- a/includes/installer/OracleUpdater.php +++ b/includes/installer/OracleUpdater.php @@ -104,6 +104,8 @@ class OracleUpdater extends DatabaseUpdater { /** * Overload: after this action field info table has to be rebuilt + * + * @param $what array */ public function doUpdates( $what = array( 'core', 'extensions', 'purge' ) ) { parent::doUpdates( $what ); diff --git a/includes/installer/SqliteInstaller.php b/includes/installer/SqliteInstaller.php index a33082fcfe..144e710d0f 100644 --- a/includes/installer/SqliteInstaller.php +++ b/includes/installer/SqliteInstaller.php @@ -14,6 +14,11 @@ */ class SqliteInstaller extends DatabaseInstaller { + /** + * @var DatabaseSqlite + */ + public $db; + protected $globalNames = array( 'wgDBname', 'wgSQLiteDataDir', @@ -47,6 +52,10 @@ class SqliteInstaller extends DatabaseInstaller { /** * Safe wrapper for PHP's realpath() that fails gracefully if it's unable to canonicalize the path. + * + * @param $path string + * + * @return string */ private static function realpath( $path ) { $result = realpath( $path ); @@ -56,14 +65,16 @@ class SqliteInstaller extends DatabaseInstaller { return $result; } + /** + * @return Status + */ public function submitConnectForm() { $this->setVarsFromRequest( array( 'wgSQLiteDataDir', 'wgDBname' ) ); # Try realpath() if the directory already exists $dir = self::realpath( $this->getVar( 'wgSQLiteDataDir' ) ); $result = self::dataDirOKmaybeCreate( $dir, true /* create? */ ); - if ( $result->isOK() ) - { + if ( $result->isOK() ) { # Try expanding again in case we've just created it $dir = self::realpath( $dir ); $this->setVar( 'wgSQLiteDataDir', $dir ); @@ -71,6 +82,11 @@ class SqliteInstaller extends DatabaseInstaller { return $result; } + /** + * @param $dir + * @param $create bool + * @return Status + */ private static function dataDirOKmaybeCreate( $dir, $create = false ) { if ( !is_dir( $dir ) ) { if ( !is_writable( dirname( $dir ) ) ) { @@ -103,6 +119,9 @@ class SqliteInstaller extends DatabaseInstaller { return Status::newGood(); } + /** + * @return Status + */ public function openConnection() { global $wgSQLiteDataDir; @@ -121,6 +140,9 @@ class SqliteInstaller extends DatabaseInstaller { return $status; } + /** + * @return bool + */ public function needsUpgrade() { $dir = $this->getVar( 'wgSQLiteDataDir' ); $dbName = $this->getVar( 'wgDBname' ); @@ -133,6 +155,9 @@ class SqliteInstaller extends DatabaseInstaller { return parent::needsUpgrade(); } + /** + * @return Status + */ public function setupDatabase() { $dir = $this->getVar( 'wgSQLiteDataDir' ); @@ -162,11 +187,18 @@ class SqliteInstaller extends DatabaseInstaller { return $this->getConnection(); } + /** + * @return Staus + */ public function createTables() { $status = parent::createTables(); return $this->setupSearchIndex( $status ); } + /** + * @param $status Status + * @return Status + */ public function setupSearchIndex( &$status ) { global $IP; @@ -181,6 +213,9 @@ class SqliteInstaller extends DatabaseInstaller { return $status; } + /** + * @return string + */ public function getLocalSettings() { $dir = LocalSettingsGenerator::escapePhpString( $this->getVar( 'wgSQLiteDataDir' ) ); return diff --git a/includes/job/DoubleRedirectJob.php b/includes/job/DoubleRedirectJob.php index dd63a85b8e..6b76734ce7 100644 --- a/includes/job/DoubleRedirectJob.php +++ b/includes/job/DoubleRedirectJob.php @@ -133,6 +133,9 @@ class DoubleRedirectJob extends Job { /** * Get the final destination of a redirect + * + * @param $title Title + * * @return false if the specified title is not a redirect, or if it is a circular redirect */ public static function getFinalDestination( $title ) { diff --git a/includes/job/JobQueue.php b/includes/job/JobQueue.php index 90bc98c9e7..0cf0e5b70a 100644 --- a/includes/job/JobQueue.php +++ b/includes/job/JobQueue.php @@ -46,6 +46,10 @@ abstract class Job { * Pop a job of a certain type. This tries less hard than pop() to * actually find a job; it may be adversely affected by concurrent job * runners. + * + * @param $type string + * + * @return Job */ static function pop_type( $type ) { wfProfilein( __METHOD__ ); diff --git a/includes/media/BMP.php b/includes/media/BMP.php index bc8381a3d0..f7dd00889a 100644 --- a/includes/media/BMP.php +++ b/includes/media/BMP.php @@ -13,22 +13,39 @@ * @ingroup Media */ class BmpHandler extends BitmapHandler { - // We never want to use .bmp in an tag + + /** + * @param $file + * @return bool + */ function mustRender( $file ) { return true; } - // Render files as PNG + /** + * Render files as PNG + * + * @param $text + * @param $mime + * @param $params + * @return array + */ function getThumbType( $text, $mime, $params = null ) { return array( 'png', 'image/png' ); } /** * Get width and height from the bmp header. + * + * @param $image + * @param $filename + * @return array */ function getImageSize( $image, $filename ) { $f = fopen( $filename, 'r' ); - if(!$f) return false; + if( !$f ) { + return false; + } $header = fread( $f, 54 ); fclose($f); diff --git a/includes/media/BitmapMetadataHandler.php b/includes/media/BitmapMetadataHandler.php index ce71a58028..2a512f7b10 100644 --- a/includes/media/BitmapMetadataHandler.php +++ b/includes/media/BitmapMetadataHandler.php @@ -39,10 +39,14 @@ class BitmapMetadataHandler { } - /** get exif info using exif class. - * Basically what used to be in BitmapHandler::getMetadata(). - * Just calls stuff in the Exif class. - */ + /** + * + * get exif info using exif class. + * Basically what used to be in BitmapHandler::getMetadata(). + * Just calls stuff in the Exif class. + * + * @param $filename string + */ function getExif ( $filename ) { if ( file_exists( $filename ) ) { $exif = new Exif( $filename ); diff --git a/includes/media/Generic.php b/includes/media/Generic.php index fb8f25786c..527dd36581 100644 --- a/includes/media/Generic.php +++ b/includes/media/Generic.php @@ -24,6 +24,8 @@ abstract class MediaHandler { /** * Get a MediaHandler for a given MIME type from the instance cache * + * @param $type string + * * @return MediaHandler */ static function getHandler( $type ) { @@ -52,16 +54,23 @@ abstract class MediaHandler { * Validate a thumbnail parameter at parse time. * Return true to accept the parameter, and false to reject it. * If you return false, the parser will do something quiet and forgiving. + * + * @param $name + * @param $value */ abstract function validateParam( $name, $value ); /** * Merge a parameter array into a string appropriate for inclusion in filenames + * + * @param $params array */ abstract function makeParamString( $params ); /** * Parse a param string made with makeParamString back into an array + * + * @param $str string */ abstract function parseParamString( $str ); @@ -69,6 +78,8 @@ abstract class MediaHandler { * Changes the parameter array as necessary, ready for transformation. * Should be idempotent. * Returns false if the parameters are unacceptable and the transform should fail + * @param $image + * @param $params */ abstract function normaliseParams( $image, &$params ); @@ -137,6 +148,8 @@ abstract class MediaHandler { /** * Get a string describing the type of metadata, for display purposes. + * + * @return string */ function getMetadataType( $image ) { return false; } diff --git a/includes/media/MediaTransformOutput.php b/includes/media/MediaTransformOutput.php index b729dd1692..f170bb9d6d 100644 --- a/includes/media/MediaTransformOutput.php +++ b/includes/media/MediaTransformOutput.php @@ -50,7 +50,7 @@ abstract class MediaTransformOutput { /** * Fetch HTML for this transform output * - * @param $options Associative array of options. Boolean options + * @param $options array Associative array of options. Boolean options * should be indicated with a value of true for true, and false or * absent for false. * @@ -78,6 +78,11 @@ abstract class MediaTransformOutput { /** * Wrap some XHTML text in an anchor tag with the given attributes + * + * @param $linkAttribs array + * @param $contents string + * + * @return string */ protected function linkWrap( $linkAttribs, $contents ) { if ( $linkAttribs ) { @@ -87,6 +92,11 @@ abstract class MediaTransformOutput { } } + /** + * @param $title string + * @param $params array + * @return array + */ function getDescLinkAttribs( $title = null, $params = '' ) { $query = $this->page ? ( 'page=' . urlencode( $this->page ) ) : ''; if( $params ) { @@ -103,7 +113,6 @@ abstract class MediaTransformOutput { } } - /** * Media transform output for images * @@ -136,7 +145,7 @@ class ThumbnailImage extends MediaTransformOutput { * Return HTML tag for the thumbnail, will include * width and height attributes and a blank alt text (as required). * - * @param $options Associative array of options. Boolean options + * @param $options array Associative array of options. Boolean options * should be indicated with a value of true for true, and false or * absent for false. * diff --git a/includes/objectcache/DBABagOStuff.php b/includes/objectcache/DBABagOStuff.php index 2c07172cde..58c434c58a 100644 --- a/includes/objectcache/DBABagOStuff.php +++ b/includes/objectcache/DBABagOStuff.php @@ -27,6 +27,8 @@ class DBABagOStuff extends BagOStuff { /** * Encode value and expiry for storage + * + * @return string */ function encode( $value, $expiry ) { # Convert to absolute time @@ -36,7 +38,7 @@ class DBABagOStuff extends BagOStuff { } /** - * @return list containing value first and expiry second + * @return array list containing value first and expiry second */ function decode( $blob ) { if ( !is_string( $blob ) ) { diff --git a/includes/objectcache/ObjectCache.php b/includes/objectcache/ObjectCache.php index 5abeee729a..a798203c0f 100644 --- a/includes/objectcache/ObjectCache.php +++ b/includes/objectcache/ObjectCache.php @@ -79,6 +79,8 @@ class ObjectCache { /** * Factory function referenced from DefaultSettings.php for CACHE_ACCEL. + * + * @return ObjectCache */ static function newAccelerator( $params ) { if ( function_exists( 'eaccelerator_get' ) ) { diff --git a/includes/objectcache/SqlBagOStuff.php b/includes/objectcache/SqlBagOStuff.php index 6952cdf0a3..7be345b3d5 100644 --- a/includes/objectcache/SqlBagOStuff.php +++ b/includes/objectcache/SqlBagOStuff.php @@ -31,6 +31,8 @@ class SqlBagOStuff extends BagOStuff { * reciprocal of the probability of purging on any given * request. If this is set to zero, purging will never be * done. + * + * @param $params array */ public function __construct( $params ) { if ( isset( $params['server'] ) ) { diff --git a/includes/parser/CoreTagHooks.php b/includes/parser/CoreTagHooks.php index 381ed5a5de..458088f0eb 100644 --- a/includes/parser/CoreTagHooks.php +++ b/includes/parser/CoreTagHooks.php @@ -53,9 +53,9 @@ class CoreTagHooks { * * Uses undocumented extended tag hook return values, introduced in r61913. * - * @param string $content - * @param array $attribs - * @param Parser $parser + * @param $content string + * @param $attribs array + * @param $parser Parser * @return array */ static function html( $content, $attributes, $parser ) { @@ -74,9 +74,9 @@ class CoreTagHooks { * * Uses undocumented extended tag hook return values, introduced in r61913. * - * @param string $content - * @param array $attribs - * @param Parser $parser + * @param $content string + * @param $attribs array + * @param $parser Parser * @return array */ static function nowiki( $content, $attributes, $parser ) { diff --git a/includes/parser/ParserCache.php b/includes/parser/ParserCache.php index 2daeb72024..af5e12408b 100644 --- a/includes/parser/ParserCache.php +++ b/includes/parser/ParserCache.php @@ -134,6 +134,11 @@ class ParserCache { /** * Retrieve the ParserOutput from ParserCache. * false if not found or outdated. + * + * @param $article Article + * @param $popts ParserOptions + * @param $useOutdated + * * @return ParserOutput|false */ public function get( $article, $popts, $useOutdated = false ) { -- 2.20.1