From b15737fa837deb410cd75568b9c6b919662842a6 Mon Sep 17 00:00:00 2001 From: Sam Reed Date: Sat, 28 May 2011 19:00:01 +0000 Subject: [PATCH] And even more documentation, the last of this batch --- includes/PoolCounter.php | 17 ++++++++- includes/Revision.php | 2 + includes/WatchedItem.php | 5 +++ includes/WebStart.php | 2 + includes/parser/ParserOutput.php | 10 +++-- includes/parser/Preprocessor.php | 2 + includes/parser/StripState.php | 37 +++++++++++++++++++ includes/search/SearchIBM_DB2.php | 2 +- includes/search/SearchMssql.php | 6 +-- includes/search/SearchMySQL.php | 2 + includes/search/SearchOracle.php | 8 +++- includes/search/SearchPostgres.php | 4 ++ includes/search/SearchSqlite.php | 6 +++ includes/specials/SpecialDisambiguations.php | 2 +- includes/specials/SpecialEditWatchlist.php | 3 -- .../specials/SpecialFileDuplicateSearch.php | 2 +- includes/specials/SpecialLinkSearch.php | 2 + .../specials/SpecialMostlinkedcategories.php | 1 + includes/specials/SpecialProtectedtitles.php | 2 + includes/specials/SpecialUploadStash.php | 12 ++---- includes/specials/SpecialWhatlinkshere.php | 1 - includes/upload/UploadBase.php | 1 + includes/upload/UploadFromFile.php | 23 ++++++++++-- includes/upload/UploadFromStash.php | 3 +- 24 files changed, 125 insertions(+), 30 deletions(-) diff --git a/includes/PoolCounter.php b/includes/PoolCounter.php index 302587d8fe..182520e1c9 100644 --- a/includes/PoolCounter.php +++ b/includes/PoolCounter.php @@ -67,6 +67,11 @@ abstract class PoolCounter { /** * Create a Pool counter. This should only be called from the PoolWorks. + * + * @param $type + * @param $key + * + * @return PoolCounter */ public static function factory( $type, $key ) { global $wgPoolCounterConf; @@ -88,18 +93,28 @@ abstract class PoolCounter { } class PoolCounter_Stub extends PoolCounter { + + /** + * @return Status + */ function acquireForMe() { return Status::newGood( PoolCounter::LOCKED ); } + /** + * @return Status + */ function acquireForAnyone() { return Status::newGood( PoolCounter::LOCKED ); } + /** + * @return Status + */ function release() { return Status::newGood( PoolCounter::RELEASED ); } - + public function __construct() { /* No parameters needed */ } diff --git a/includes/Revision.php b/includes/Revision.php index 61a837e9bc..66501d2965 100644 --- a/includes/Revision.php +++ b/includes/Revision.php @@ -66,6 +66,8 @@ class Revision { * Make a fake revision object from an archive table row. This is queried * for permissions or even inserted (as in Special:Undelete) * @todo FIXME: Should be a subclass for RevisionDelete. [TS] + * + * @return Revision */ public static function newFromArchiveRow( $row, $overrides = array() ) { $attribs = $overrides + array( diff --git a/includes/WatchedItem.php b/includes/WatchedItem.php index dd6e247b92..031b2b48b0 100644 --- a/includes/WatchedItem.php +++ b/includes/WatchedItem.php @@ -133,6 +133,11 @@ class WatchedItem { /** * Handle duplicate entries. Backend for duplicateEntries(). + * + * @param $ot Title + * @param $nt Title + * + * @return bool */ private static function doDuplicateEntries( $ot, $nt ) { $oldnamespace = $ot->getNamespace(); diff --git a/includes/WebStart.php b/includes/WebStart.php index 604f79f325..feb80398a0 100644 --- a/includes/WebStart.php +++ b/includes/WebStart.php @@ -12,6 +12,8 @@ * Detect compiled mode by looking for a function that only exists if compiled * in. Note that we can't use function_exists(), because it is terribly broken * under HipHop due to the "volatile" feature. + * + * @return bool */ function wfDetectCompiledMode() { try { diff --git a/includes/parser/ParserOutput.php b/includes/parser/ParserOutput.php index 39da818f47..b27d077669 100644 --- a/includes/parser/ParserOutput.php +++ b/includes/parser/ParserOutput.php @@ -21,10 +21,12 @@ class CacheTime { function containsOldMagic() { return $this->mContainsOldMagic; } function setContainsOldMagic( $com ) { return wfSetVar( $this->mContainsOldMagic, $com ); } - - /** - * setCacheTime() sets the timestamp expressing when the page has been rendered. + + /** + * setCacheTime() sets the timestamp expressing when the page has been rendered. * This doesn not control expiry, see updateCacheExpiry() for that! + * @param $t string + * @return string */ function setCacheTime( $t ) { return wfSetVar( $this->mCacheTime, $t ); } @@ -35,6 +37,8 @@ class CacheTime { * the new call has no effect. The value returned by getCacheExpiry is smaller * or equal to the smallest number that was provided as an argument to * updateCacheExpiry(). + * + * @param $seconds number */ function updateCacheExpiry( $seconds ) { $seconds = (int)$seconds; diff --git a/includes/parser/Preprocessor.php b/includes/parser/Preprocessor.php index 1e9343b56d..d6328aa738 100644 --- a/includes/parser/Preprocessor.php +++ b/includes/parser/Preprocessor.php @@ -128,6 +128,8 @@ interface PPFrame { /** * Returns true if the infinite loop check is OK, false if a loop is detected * + * @param $title + * * @return bool */ function loopCheck( $title ); diff --git a/includes/parser/StripState.php b/includes/parser/StripState.php index 0bf9e17ace..c7bd1e77d9 100644 --- a/includes/parser/StripState.php +++ b/includes/parser/StripState.php @@ -22,15 +22,27 @@ class StripState { /** * Add a nowiki strip item + * @param $marker + * @param $value */ function addNoWiki( $marker, $value ) { $this->addItem( 'nowiki', $marker, $value ); } + /** + * @param $marker + * @param $value + */ function addGeneral( $marker, $value ) { $this->addItem( 'general', $marker, $value ); } + /** + * @throws MWException + * @param $type + * @param $marker + * @param $value + */ protected function addItem( $type, $marker, $value ) { if ( !preg_match( $this->regex, $marker, $m ) ) { throw new MWException( "Invalid marker: $marker" ); @@ -39,20 +51,37 @@ class StripState { $this->data[$type][$m[1]] = $value; } + /** + * @param $text + * @return mixed + */ function unstripGeneral( $text ) { return $this->unstripType( 'general', $text ); } + /** + * @param $text + * @return mixed + */ function unstripNoWiki( $text ) { return $this->unstripType( 'nowiki', $text ); } + /** + * @param $text + * @return mixed + */ function unstripBoth( $text ) { $text = $this->unstripType( 'general', $text ); $text = $this->unstripType( 'nowiki', $text ); return $text; } + /** + * @param $type + * @param $text + * @return mixed + */ protected function unstripType( $type, $text ) { // Shortcut if ( !count( $this->data[$type] ) ) { @@ -67,6 +96,10 @@ class StripState { return $out; } + /** + * @param $m array + * @return array + */ protected function unstripCallback( $m ) { if ( isset( $this->data[$this->tempType][$m[1]] ) ) { return $this->data[$this->tempType][$m[1]]; @@ -78,6 +111,10 @@ class StripState { /** * Get a StripState object which is sufficient to unstrip the given text. * It will contain the minimum subset of strip items necessary. + * + * @param $text string + * + * @return StripState */ function getSubState( $text ) { $subState = new StripState( $this->prefix ); diff --git a/includes/search/SearchIBM_DB2.php b/includes/search/SearchIBM_DB2.php index 732573f519..c02a009dec 100644 --- a/includes/search/SearchIBM_DB2.php +++ b/includes/search/SearchIBM_DB2.php @@ -91,7 +91,7 @@ class SearchIBM_DB2 extends SearchEngine { * Return a LIMIT clause to limit results on the query. * @return String */ - function queryLimit($sql) { + function queryLimit( $sql ) { return $this->db->limitResult($sql, $this->limit, $this->offset); } diff --git a/includes/search/SearchMssql.php b/includes/search/SearchMssql.php index b74fd7b276..ebf19d3a8f 100644 --- a/includes/search/SearchMssql.php +++ b/includes/search/SearchMssql.php @@ -91,8 +91,9 @@ class SearchMssql extends SearchEngine { /** * Return a LIMIT clause to limit results on the query. * + * @param $sql string + * * @return String - * @private */ function queryLimit( $sql ) { return $this->db->limitResult( $sql, $this->limit, $this->offset ); @@ -103,7 +104,6 @@ class SearchMssql extends SearchEngine { * subclasses may define this though * * @return String - * @private */ function queryRanking( $filteredTerm, $fulltext ) { return ' ORDER BY ftindex.[RANK] DESC'; // return ' ORDER BY score(1)'; @@ -115,7 +115,6 @@ class SearchMssql extends SearchEngine { * * @param $filteredTerm String * @param $fulltext Boolean - * @private */ function getQuery( $filteredTerm, $fulltext ) { return $this->queryLimit( $this->queryMain( $filteredTerm, $fulltext ) . ' ' . @@ -124,7 +123,6 @@ class SearchMssql extends SearchEngine { $this->queryRanking( $filteredTerm, $fulltext ) . ' ' ); } - /** * Picks which field to index on, depending on what type of query. * diff --git a/includes/search/SearchMySQL.php b/includes/search/SearchMySQL.php index 1a478d7f60..51c73b6c09 100644 --- a/includes/search/SearchMySQL.php +++ b/includes/search/SearchMySQL.php @@ -43,6 +43,8 @@ class SearchMySQL extends SearchEngine { /** * Parse the user's query and transform it into an SQL fragment which will * become part of a WHERE clause + * + * @return string */ function parseQuery( $filteredText, $fulltext ) { global $wgContLang; diff --git a/includes/search/SearchOracle.php b/includes/search/SearchOracle.php index d9ad299eb3..85337ca17a 100644 --- a/includes/search/SearchOracle.php +++ b/includes/search/SearchOracle.php @@ -123,18 +123,22 @@ class SearchOracle extends SearchEngine { /** * Return a LIMIT clause to limit results on the query. + * + * @param string + * * @return String */ - function queryLimit($sql) { + function queryLimit( $sql ) { return $this->db->limitResult($sql, $this->limit, $this->offset); } /** * Does not do anything for generic search engine * subclasses may define this though + * * @return String */ - function queryRanking($filteredTerm, $fulltext) { + function queryRanking( $filteredTerm, $fulltext ) { return ' ORDER BY score(1)'; } diff --git a/includes/search/SearchPostgres.php b/includes/search/SearchPostgres.php index b0590d0f69..5fd7415c8b 100644 --- a/includes/search/SearchPostgres.php +++ b/includes/search/SearchPostgres.php @@ -70,6 +70,10 @@ class SearchPostgres extends SearchEngine { /** * Transform the user's search string into a better form for tsearch2 * Returns an SQL fragment consisting of quoted text to search for. + * + * @param $term string + * + * @return string */ function parseQuery( $term ) { diff --git a/includes/search/SearchSqlite.php b/includes/search/SearchSqlite.php index 6accc31b29..d58b7b91d5 100644 --- a/includes/search/SearchSqlite.php +++ b/includes/search/SearchSqlite.php @@ -26,6 +26,12 @@ * @ingroup Search */ class SearchSqlite extends SearchEngine { + + /** + * @var DatabaseSqlite + */ + protected $db; + /** * Creates an instance of this class * @param $db DatabaseSqlite: database object diff --git a/includes/specials/SpecialDisambiguations.php b/includes/specials/SpecialDisambiguations.php index adbae7978d..e62253bc12 100644 --- a/includes/specials/SpecialDisambiguations.php +++ b/includes/specials/SpecialDisambiguations.php @@ -105,6 +105,7 @@ class DisambiguationsPage extends PageQueryPage { * Fetch links and cache their existence * * @param $db DatabaseBase + * @param $res */ function preprocessResults( $db, $res ) { $batch = new LinkBatch; @@ -120,7 +121,6 @@ class DisambiguationsPage extends PageQueryPage { } } - function formatResult( $skin, $result ) { global $wgContLang; $title = Title::newFromID( $result->value ); diff --git a/includes/specials/SpecialEditWatchlist.php b/includes/specials/SpecialEditWatchlist.php index a53b581052..47576e3523 100644 --- a/includes/specials/SpecialEditWatchlist.php +++ b/includes/specials/SpecialEditWatchlist.php @@ -25,9 +25,6 @@ class SpecialEditWatchlist extends UnlistedSpecialPage { /** * Main execution point * - * @param $user User - * @param $output OutputPage - * @param $request WebRequest * @param $mode int */ public function execute( $mode ) { diff --git a/includes/specials/SpecialFileDuplicateSearch.php b/includes/specials/SpecialFileDuplicateSearch.php index 8ae2d54d35..4009fe6b82 100644 --- a/includes/specials/SpecialFileDuplicateSearch.php +++ b/includes/specials/SpecialFileDuplicateSearch.php @@ -59,7 +59,7 @@ class FileDuplicateSearchPage extends QueryPage { /** * - * @param Array of File objects $dupes + * @param $dupes Array of File objects */ function showList( $dupes ) { global $wgUser, $wgOut; diff --git a/includes/specials/SpecialLinkSearch.php b/includes/specials/SpecialLinkSearch.php index 623504d8e6..7ecad851d8 100644 --- a/includes/specials/SpecialLinkSearch.php +++ b/includes/specials/SpecialLinkSearch.php @@ -114,6 +114,8 @@ class LinkSearchPage extends QueryPage { /** * Return an appropriately formatted LIKE query and the clause + * + * @return array */ static function mungeQuery( $query, $prot ) { $field = 'el_index'; diff --git a/includes/specials/SpecialMostlinkedcategories.php b/includes/specials/SpecialMostlinkedcategories.php index 242e26fb84..195282f7d9 100644 --- a/includes/specials/SpecialMostlinkedcategories.php +++ b/includes/specials/SpecialMostlinkedcategories.php @@ -54,6 +54,7 @@ class MostlinkedCategoriesPage extends QueryPage { * Fetch user page links and cache their existence * * @param $db DatabaseBase + * @param $res DatabaseResult */ function preprocessResults( $db, $res ) { $batch = new LinkBatch; diff --git a/includes/specials/SpecialProtectedtitles.php b/includes/specials/SpecialProtectedtitles.php index 51528bcc4a..e347894ff4 100644 --- a/includes/specials/SpecialProtectedtitles.php +++ b/includes/specials/SpecialProtectedtitles.php @@ -70,6 +70,8 @@ class SpecialProtectedtitles extends SpecialPage { /** * Callback function to output a restriction + * + * @return string */ function formatRow( $row ) { global $wgUser, $wgLang; diff --git a/includes/specials/SpecialUploadStash.php b/includes/specials/SpecialUploadStash.php index f262c0a80f..de0057fb14 100644 --- a/includes/specials/SpecialUploadStash.php +++ b/includes/specials/SpecialUploadStash.php @@ -133,13 +133,12 @@ class SpecialUploadStash extends UnlistedSpecialPage { return array( 'file' => $file, 'type' => $type ); } - - - /** * Get a thumbnail for file, either generated locally or remotely, and stream it out - * @param String $key: key for the file in the stash - * @param int $width: width of desired thumbnail + * + * @param $file + * @param $params array + * * @return boolean success */ private function outputThumbFromStash( $file, $params ) { @@ -155,11 +154,8 @@ class SpecialUploadStash extends UnlistedSpecialPage { } else { $this->outputLocallyScaledThumb( $file, $params, $flags ); } - - } - /** * Scale a file (probably with a locally installed imagemagick, or similar) and output it to STDOUT. * @param $file: File object diff --git a/includes/specials/SpecialWhatlinkshere.php b/includes/specials/SpecialWhatlinkshere.php index 8b4eeefb92..631315ea5b 100644 --- a/includes/specials/SpecialWhatlinkshere.php +++ b/includes/specials/SpecialWhatlinkshere.php @@ -98,7 +98,6 @@ class SpecialWhatLinksHere extends SpecialPage { * @param $limit int Number of entries to display * @param $from Title Display from this article ID * @param $back Title Display from this article ID at backwards scrolling - * @private */ function showIndirectLinks( $level, $target, $limit, $from = 0, $back = 0 ) { global $wgMaxRedirectLinksRetrieved; diff --git a/includes/upload/UploadBase.php b/includes/upload/UploadBase.php index ba8fc2afb1..d0f61e5997 100644 --- a/includes/upload/UploadBase.php +++ b/includes/upload/UploadBase.php @@ -102,6 +102,7 @@ abstract class UploadBase { * Create a form of UploadBase depending on wpSourceType and initializes it * * @param $request WebRequest + * @param $type */ public static function createFromRequest( &$request, $type = null ) { $type = $type ? $type : $request->getVal( 'wpSourceType', 'File' ); diff --git a/includes/upload/UploadFromFile.php b/includes/upload/UploadFromFile.php index b094828a18..c2ab6467e9 100644 --- a/includes/upload/UploadFromFile.php +++ b/includes/upload/UploadFromFile.php @@ -25,23 +25,38 @@ class UploadFromFile extends UploadBase { return $this->initialize( $desiredDestName, $upload ); } - + /** * Initialize from a filename and a WebRequestUpload + * @param $name + * @param $webRequestUpload */ function initialize( $name, $webRequestUpload ) { $this->mUpload = $webRequestUpload; return $this->initializePathInfo( $name, $this->mUpload->getTempName(), $this->mUpload->getSize() ); } + + /** + * @param $request + * @return bool + */ static function isValidRequest( $request ) { # Allow all requests, even if no file is present, so that an error # because a post_max_size or upload_max_filesize overflow return true; } - - public function getSourceType() { return 'file'; } - + + /** + * @return string + */ + public function getSourceType() { + return 'file'; + } + + /** + * @return array + */ public function verifyUpload() { # Check for a post_max_size or upload_max_size overflow, so that a # proper error can be shown to the user diff --git a/includes/upload/UploadFromStash.php b/includes/upload/UploadFromStash.php index 50974c329c..2ceea0d5cb 100644 --- a/includes/upload/UploadFromStash.php +++ b/includes/upload/UploadFromStash.php @@ -82,8 +82,9 @@ class UploadFromStash extends UploadBase { * There is no need to stash the image twice */ public function stashSession( $key = null ) { - if ( !empty( $this->mSessionKey ) ) + if ( !empty( $this->mSessionKey ) ) { return $this->mSessionKey; + } return parent::stashSession(); } -- 2.20.1