From 3614ecfffb7dc7251951e00c02d20ab4275fd5bd Mon Sep 17 00:00:00 2001 From: Sam Reed Date: Sat, 28 May 2011 17:18:50 +0000 Subject: [PATCH] And more documentation. Yaaaay --- includes/Autopromote.php | 2 +- includes/Cdb_PHP.php | 59 ++++++++++++++++++- includes/HistoryBlob.php | 61 ++++++++++++++++++-- includes/ImageFunctions.php | 2 +- includes/OutputHandler.php | 4 +- includes/StreamFile.php | 5 +- includes/ZhClient.php | 4 ++ includes/filerepo/FileRepoStatus.php | 9 +++ includes/media/IPTC.php | 2 +- includes/media/Tiff.php | 45 ++++++++++----- includes/objectcache/MultiWriteBagOStuff.php | 2 + includes/objectcache/ObjectCache.php | 10 ++++ includes/parser/Parser.php | 37 ++++++++++-- includes/parser/Preprocessor.php | 4 ++ includes/specials/SpecialListredirects.php | 1 + 15 files changed, 215 insertions(+), 32 deletions(-) diff --git a/includes/Autopromote.php b/includes/Autopromote.php index b4d89b24ac..97043da2ab 100644 --- a/includes/Autopromote.php +++ b/includes/Autopromote.php @@ -8,7 +8,7 @@ class Autopromote { /** * Get the groups for the given user based on $wgAutopromote. * - * @param $user The user to get the groups for + * @param $user User The user to get the groups for * @return array Array of groups to promote to. */ public static function getAutopromoteGroups( User $user ) { diff --git a/includes/Cdb_PHP.php b/includes/Cdb_PHP.php index 1485cc6698..70dccdf9ad 100644 --- a/includes/Cdb_PHP.php +++ b/includes/Cdb_PHP.php @@ -16,6 +16,7 @@ class CdbFunctions { /** * Take a modulo of a signed integer as if it were an unsigned integer. * $b must be less than 0x40000000 and greater than 0 + * @return int */ public static function unsignedMod( $a, $b ) { if ( $a & 0x80000000 ) { @@ -25,9 +26,12 @@ class CdbFunctions { return $a % $b; } } - + /** * Shift a signed integer right as if it were unsigned + * @param $a + * @param $b + * @return int */ public static function unsignedShiftRight( $a, $b ) { if ( $b == 0 ) { @@ -42,6 +46,9 @@ class CdbFunctions { /** * The CDB hash function. + * + * @param $s + * @return */ public static function hash( $s ) { $h = 5381; @@ -103,8 +110,9 @@ class CdbReader_PHP extends CdbReader { } function close() { - if( isset($this->handle) ) + if( isset( $this->handle ) ) { fclose( $this->handle ); + } unset( $this->handle ); } @@ -117,6 +125,11 @@ class CdbReader_PHP extends CdbReader { } } + /** + * @param $key + * @param $pos + * @return bool + */ protected function match( $key, $pos ) { $buf = $this->read( strlen( $key ), $pos ); return $buf === $key; @@ -126,6 +139,12 @@ class CdbReader_PHP extends CdbReader { $this->loop = 0; } + /** + * @throws MWException + * @param $length + * @param $pos + * @return string + */ protected function read( $length, $pos ) { if ( fseek( $this->handle, $pos ) == -1 ) { // This can easily happen if the internal pointers are incorrect @@ -145,6 +164,8 @@ class CdbReader_PHP extends CdbReader { /** * Unpack an unsigned integer and throw an exception if it needs more than 31 bits + * @param $s + * @return */ protected function unpack31( $s ) { $data = unpack( 'V', $s ); @@ -156,12 +177,18 @@ class CdbReader_PHP extends CdbReader { /** * Unpack a 32-bit signed integer + * @param $s + * @return int */ protected function unpackSigned( $s ) { $data = unpack( 'va/vb', $s ); return $data['a'] | ( $data['b'] << 16 ); } + /** + * @param $key + * @return bool + */ protected function findNext( $key ) { if ( !$this->loop ) { $u = CdbFunctions::hash( $key ); @@ -204,6 +231,10 @@ class CdbReader_PHP extends CdbReader { return false; } + /** + * @param $key + * @return bool + */ protected function find( $key ) { $this->findStart(); return $this->findNext( $key ); @@ -240,6 +271,11 @@ class CdbWriter_PHP extends CdbWriter { } } + /** + * @param $key + * @param $value + * @return + */ public function set( $key, $value ) { if ( strval( $key ) === '' ) { // DBA cross-check hack @@ -251,10 +287,14 @@ class CdbWriter_PHP extends CdbWriter { $this->addend( strlen( $key ), strlen( $value ), CdbFunctions::hash( $key ) ); } + /** + * @throws MWException + */ public function close() { $this->finish(); - if( isset($this->handle) ) + if( isset($this->handle) ) { fclose( $this->handle ); + } if ( wfIsWindows() && file_exists($this->realFileName) ) { unlink( $this->realFileName ); } @@ -264,6 +304,10 @@ class CdbWriter_PHP extends CdbWriter { unset( $this->handle ); } + /** + * @throws MWException + * @param $buf + */ protected function write( $buf ) { $len = fwrite( $this->handle, $buf ); if ( $len !== strlen( $buf ) ) { @@ -271,6 +315,10 @@ class CdbWriter_PHP extends CdbWriter { } } + /** + * @throws MWException + * @param $len + */ protected function posplus( $len ) { $newpos = $this->pos + $len; if ( $newpos > 0x7fffffff ) { @@ -291,6 +339,11 @@ class CdbWriter_PHP extends CdbWriter { $this->posplus( $datalen ); } + /** + * @throws MWException + * @param $keylen + * @param $datalen + */ protected function addbegin( $keylen, $datalen ) { if ( $keylen > 0x7fffffff ) { throw new MWException( __METHOD__.': key length too long' ); diff --git a/includes/HistoryBlob.php b/includes/HistoryBlob.php index 15f767e10b..3fc27a2944 100644 --- a/includes/HistoryBlob.php +++ b/includes/HistoryBlob.php @@ -12,6 +12,8 @@ interface HistoryBlob * You must call setLocation() on the stub object before storing it to the * database * + * @param $text string + * * @return String: the key for getItem() */ function addItem( $text ); @@ -19,6 +21,8 @@ interface HistoryBlob /** * Get item by key, or false if the key is not present * + * @param $key string + * * @return String or false */ function getItem( $key ); @@ -30,6 +34,8 @@ interface HistoryBlob * be other revisions in the same object. * * Default text is not required for two-part external storage URLs. + * + * @param $text string */ function setText( $text ); @@ -59,6 +65,10 @@ class ConcatenatedGzipHistoryBlob implements HistoryBlob } } + /** + * @param $text string + * @return string + */ public function addItem( $text ) { $this->uncompress(); $hash = md5( $text ); @@ -69,6 +79,10 @@ class ConcatenatedGzipHistoryBlob implements HistoryBlob return $hash; } + /** + * @param $hash string + * @return array|bool + */ public function getItem( $hash ) { $this->uncompress(); if ( array_key_exists( $hash, $this->mItems ) ) { @@ -78,11 +92,18 @@ class ConcatenatedGzipHistoryBlob implements HistoryBlob } } + /** + * @param $text string + * @return void + */ public function setText( $text ) { $this->uncompress(); $this->mDefaultHash = $this->addItem( $text ); } + /** + * @return array|bool + */ public function getText() { $this->uncompress(); return $this->getItem( $this->mDefaultHash ); @@ -90,6 +111,8 @@ class ConcatenatedGzipHistoryBlob implements HistoryBlob /** * Remove an item + * + * @param $hash string */ public function removeItem( $hash ) { $this->mSize -= strlen( $this->mItems[$hash] ); @@ -116,7 +139,9 @@ class ConcatenatedGzipHistoryBlob implements HistoryBlob } } - + /** + * @return array + */ function __sleep() { $this->compress(); return array( 'mVersion', 'mCompressed', 'mItems', 'mDefaultHash' ); @@ -129,6 +154,8 @@ class ConcatenatedGzipHistoryBlob implements HistoryBlob /** * Helper function for compression jobs * Returns true until the object is "full" and ready to be committed + * + * @return bool */ public function isHappy() { return $this->mSize < $this->mMaxSize @@ -137,8 +164,6 @@ class ConcatenatedGzipHistoryBlob implements HistoryBlob } - - /** * Pointer object for an item within a CGZ blob stored in the text table. */ @@ -183,6 +208,9 @@ class HistoryBlobStub { return $this->mRef; } + /** + * @return string + */ function getText() { $fname = 'HistoryBlobStub::getText'; @@ -198,11 +226,11 @@ class HistoryBlobStub { if( in_array( 'external', $flags ) ) { $url=$row->old_text; @list( /* $proto */ ,$path)=explode('://',$url,2); - if ($path=="") { + if ( $path == "" ) { wfProfileOut( $fname ); return false; } - $row->old_text=ExternalStore::fetchFromUrl($url); + $row->old_text = ExternalStore::fetchFromUrl($url); } if( !in_array( 'object', $flags ) ) { @@ -232,6 +260,8 @@ class HistoryBlobStub { /** * Get the content hash + * + * @return string */ function getHash() { return $this->mHash; @@ -265,6 +295,9 @@ class HistoryBlobCurStub { $this->mCurId = $id; } + /** + * @return string|false + */ function getText() { $dbr = wfGetDB( DB_SLAVE ); $row = $dbr->selectRow( 'cur', array( 'cur_text' ), array( 'cur_id' => $this->mCurId ) ); @@ -336,6 +369,11 @@ class DiffHistoryBlob implements HistoryBlob { } } + /** + * @throws MWException + * @param $text string + * @return int + */ function addItem( $text ) { if ( $this->mFrozen ) { throw new MWException( __METHOD__.": Cannot add more items after sleep/wakeup" ); @@ -347,18 +385,31 @@ class DiffHistoryBlob implements HistoryBlob { return count( $this->mItems ) - 1; } + /** + * @param $key string + * @return string + */ function getItem( $key ) { return $this->mItems[$key]; } + /** + * @param $text string + */ function setText( $text ) { $this->mDefaultKey = $this->addItem( $text ); } + /** + * @return string + */ function getText() { return $this->getItem( $this->mDefaultKey ); } + /** + * @throws MWException + */ function compress() { if ( !function_exists( 'xdiff_string_rabdiff' ) ){ throw new MWException( "Need xdiff 1.5+ support to write DiffHistoryBlob\n" ); diff --git a/includes/ImageFunctions.php b/includes/ImageFunctions.php index 8eaebd2699..2af77dde24 100644 --- a/includes/ImageFunctions.php +++ b/includes/ImageFunctions.php @@ -15,7 +15,7 @@ * i.e. articles where the image may occur inline. * * @param $name string the image name to check - * @param $contextTitle Title: the page on which the image occurs, if known + * @param $contextTitle Title the page on which the image occurs, if known * @return bool */ function wfIsBadImage( $name, $contextTitle = false ) { diff --git a/includes/OutputHandler.php b/includes/OutputHandler.php index f655e784ad..4112f8a27c 100644 --- a/includes/OutputHandler.php +++ b/includes/OutputHandler.php @@ -7,7 +7,9 @@ /** * Standard output handler for use with ob_start - * + * + * @param $s string + * * @return string */ function wfOutputHandler( $s ) { diff --git a/includes/StreamFile.php b/includes/StreamFile.php index 0982a0371f..f2f0566e86 100644 --- a/includes/StreamFile.php +++ b/includes/StreamFile.php @@ -5,7 +5,10 @@ * @file */ -/** */ +/** + * @param $fname string + * @param $headers array + */ function wfStreamFile( $fname, $headers = array() ) { $stat = @stat( $fname ); if ( !$stat ) { diff --git a/includes/ZhClient.php b/includes/ZhClient.php index 5404b696fb..7807319e92 100644 --- a/includes/ZhClient.php +++ b/includes/ZhClient.php @@ -19,6 +19,8 @@ class ZhClient { /** * Check if connection to zhdaemon is successful + * + * @return bool */ function isconnected() { return $this->mConnected; @@ -28,6 +30,8 @@ class ZhClient { * Establish conncetion * * @access private + * + * @return bool */ function connect() { wfSuppressWarnings(); diff --git a/includes/filerepo/FileRepoStatus.php b/includes/filerepo/FileRepoStatus.php index 24d7331562..4eea903030 100644 --- a/includes/filerepo/FileRepoStatus.php +++ b/includes/filerepo/FileRepoStatus.php @@ -13,6 +13,10 @@ class FileRepoStatus extends Status { /** * Factory function for fatal errors + * + * @param $repo FileRepo + * + * @return FileRepoStatus */ static function newFatal( $repo /*, parameters...*/ ) { $params = array_slice( func_get_args(), 1 ); @@ -22,6 +26,11 @@ class FileRepoStatus extends Status { return $result; } + /** + * @param $repo FileRepo + * @param $value + * @return FileRepoStatus + */ static function newGood( $repo = false, $value = null ) { $result = new self( $repo ); $result->value = $value; diff --git a/includes/media/IPTC.php b/includes/media/IPTC.php index a86833ab32..1d19791cab 100644 --- a/includes/media/IPTC.php +++ b/includes/media/IPTC.php @@ -12,7 +12,7 @@ class IPTC { * * @see http://www.iptc.org/std/IIM/4.1/specification/IIMV4.1.pdf * - * @param String $data app13 block from jpeg containing iptc/iim data + * @param $rawData String app13 block from jpeg containing iptc/iim data * @return Array iptc metadata array */ static function parse( $rawData ) { diff --git a/includes/media/Tiff.php b/includes/media/Tiff.php index ef0621b75a..51e3194d6f 100644 --- a/includes/media/Tiff.php +++ b/includes/media/Tiff.php @@ -16,6 +16,8 @@ class TiffHandler extends JpegOrTiffHandler { /** * Conversion to PNG for inline display can be disabled here... * Note scaling should work with ImageMagick, but may not with GD scaling. + * + * @return bool */ function canRender( $file ) { global $wgTiffThumbnailType; @@ -25,29 +27,42 @@ class TiffHandler extends JpegOrTiffHandler { /** * Browsers don't support TIFF inline generally... * For inline display, we need to convert to PNG. + * + * @return bool */ function mustRender( $file ) { return true; } + /** + * @param $ext + * @param $mime + * @param null $params + * @return bool + */ function getThumbType( $ext, $mime, $params = null ) { global $wgTiffThumbnailType; return $wgTiffThumbnailType; } - function getMetadata( $image, $filename ) { - global $wgShowEXIF; - if ( $wgShowEXIF && file_exists( $filename ) ) { - $exif = new Exif( $filename ); - $data = $exif->getFilteredData(); - if ( $data ) { - $data['MEDIAWIKI_EXIF_VERSION'] = Exif::version(); - return serialize( $data ); - } else { - return JpegOrTiffHandler::BROKEN_FILE; - } - } else { - return ''; - } - } + /** + * @param $image + * @param $filename + * @return string + */ + function getMetadata( $image, $filename ) { + global $wgShowEXIF; + if ( $wgShowEXIF && file_exists( $filename ) ) { + $exif = new Exif( $filename ); + $data = $exif->getFilteredData(); + if ( $data ) { + $data['MEDIAWIKI_EXIF_VERSION'] = Exif::version(); + return serialize( $data ); + } else { + return JpegOrTiffHandler::BROKEN_FILE; + } + } else { + return ''; + } + } } diff --git a/includes/objectcache/MultiWriteBagOStuff.php b/includes/objectcache/MultiWriteBagOStuff.php index 0cb47c9a62..4ed1188d35 100644 --- a/includes/objectcache/MultiWriteBagOStuff.php +++ b/includes/objectcache/MultiWriteBagOStuff.php @@ -14,6 +14,8 @@ class MultiWriteBagOStuff extends BagOStuff { * - caches: This should have a numbered array of cache parameter * structures, in the style required by $wgObjectCaches. See * the documentation of $wgObjectCaches for more detail. + * + * @param $params array */ public function __construct( $params ) { if ( !isset( $params['caches'] ) ) { diff --git a/includes/objectcache/ObjectCache.php b/includes/objectcache/ObjectCache.php index 118aadfe27..5abeee729a 100644 --- a/includes/objectcache/ObjectCache.php +++ b/includes/objectcache/ObjectCache.php @@ -10,6 +10,10 @@ class ObjectCache { /** * Get a cached instance of the specified type of cache object. + * + * @param $id + * + * @return object */ static function getInstance( $id ) { if ( isset( self::$instances[$id] ) ) { @@ -44,6 +48,8 @@ class ObjectCache { /** * Create a new cache object from parameters + * + * @param $params array */ static function newFromParams( $params ) { if ( isset( $params['factory'] ) ) { @@ -94,6 +100,10 @@ class ObjectCache { * Factory function that creates a memcached client object. * The idea of this is that it might eventually detect and automatically * support the PECL extension, assuming someone can get it to compile. + * + * @param $params array + * + * @return MemcachedPhpBagOStuff */ static function newMemcached( $params ) { return new MemcachedPhpBagOStuff( $params ); diff --git a/includes/parser/Parser.php b/includes/parser/Parser.php index 6224ae4e8e..0d60f9c89d 100644 --- a/includes/parser/Parser.php +++ b/includes/parser/Parser.php @@ -111,6 +111,10 @@ class Parser { var $mFirstCall = true; # Initialised by initialiseVariables() + + /** + * @var MagicWordArray + */ var $mVariables; /** @@ -168,6 +172,11 @@ class Parser { var $mRevisionUser; # Userto display in {{REVISIONUSER}} tag var $mRevIdForTs; # The revision ID which was used to fetch the timestamp + /** + * @var string + */ + var $mUniqPrefix; + /** * Constructor */ @@ -507,6 +516,8 @@ class Parser { /** * Get a random string + * + * @return string */ static public function getRandomString() { return dechex( mt_rand( 0, 0x7fffffff ) ) . dechex( mt_rand( 0, 0x7fffffff ) ); @@ -542,6 +553,8 @@ class Parser { /** * Set the context title + * + * @param $t Title */ function setTitle( $t ) { if ( !$t || $t instanceof FakeTitle ) { @@ -630,10 +643,16 @@ class Parser { return wfSetVar( $this->mOptions, $x ); } + /** + * @return int + */ function nextLinkID() { return $this->mLinkID++; } + /** + * @param $id int + */ function setLinkID( $id ) { $this->mLinkID = $id; } @@ -689,10 +708,10 @@ class Parser { * array( 'param' => 'x' ), * 'tag content' ) ) * - * @param $elements list of element names. Comments are always extracted. - * @param $text Source text string. - * @param $matches Out parameter, Array: extracted tags - * @param $uniq_prefix + * @param $elements array list of element names. Comments are always extracted. + * @param $text string Source text string. + * @param $matches array Out parameter, Array: extracted tags + * @param $uniq_prefix string * @return String: stripped text */ public static function extractTagsAndParams( $elements, $text, &$matches, $uniq_prefix = '' ) { @@ -759,6 +778,8 @@ class Parser { /** * Get a list of strippable XML-like elements + * + * @return array */ function getStripList() { return $this->mStripList; @@ -960,6 +981,9 @@ class Parser { * is repeated twice. * * @private + * @param $cell + * @param $tagName + * @return array */ function getCellAttr ( $cell, $tagName ) { $attributes = null; @@ -1176,6 +1200,11 @@ class Parser { return $text; } + /** + * @throws MWException + * @param $m array + * @return HTML|string + */ function magicLinkCallback( $m ) { if ( isset( $m[1] ) && $m[1] !== '' ) { # Skip anchor diff --git a/includes/parser/Preprocessor.php b/includes/parser/Preprocessor.php index eba6869e22..8eac6f0f3d 100644 --- a/includes/parser/Preprocessor.php +++ b/includes/parser/Preprocessor.php @@ -22,6 +22,8 @@ interface Preprocessor { /** * Create a new custom frame for programmatic use of parameter replacement as used in some extensions * + * @param $args array + * * @return PPFrame */ function newCustomFrame( $args ); @@ -51,6 +53,8 @@ interface PPFrame { /** * Create a child frame + * + * @return PPFrame */ function newChild( $args = false, $title = false ); diff --git a/includes/specials/SpecialListredirects.php b/includes/specials/SpecialListredirects.php index fc35b48e63..bb47c7b5a0 100644 --- a/includes/specials/SpecialListredirects.php +++ b/includes/specials/SpecialListredirects.php @@ -65,6 +65,7 @@ class ListredirectsPage extends QueryPage { * Cache page existence for performance * * @param $db DatabaseBase + * @param $res ResultWrapper */ function preprocessResults( $db, $res ) { $batch = new LinkBatch; -- 2.20.1