From d537d96868d76dc366dca818814686e2fd4c1cca Mon Sep 17 00:00:00 2001 From: Reedy Date: Sun, 9 Dec 2012 03:09:48 +0000 Subject: [PATCH] Add numerous missing @throws to method documentation Change-Id: Iba868e82a75fef7c7d011bc5be192bf059d037c0 --- includes/Action.php | 5 +++-- includes/Hooks.php | 2 ++ includes/LinksUpdate.php | 1 + includes/Title.php | 2 ++ includes/User.php | 1 + includes/UserMailer.php | 2 ++ includes/WebRequest.php | 1 + includes/WikiPage.php | 5 ++++- includes/cache/MessageCache.php | 3 ++- includes/content/ContentHandler.php | 1 + includes/db/Database.php | 2 ++ includes/filebackend/SwiftFileBackend.php | 3 ++- includes/job/JobQueue.php | 3 +++ includes/job/JobQueueDB.php | 7 +++++++ includes/job/JobQueueGroup.php | 1 + includes/objectcache/SqlBagOStuff.php | 1 + includes/site/SiteObject.php | 1 + includes/specials/SpecialBooksources.php | 1 + includes/specials/SpecialUndelete.php | 3 ++- 19 files changed, 39 insertions(+), 6 deletions(-) diff --git a/includes/Action.php b/includes/Action.php index 19552bc2e4..82017632d4 100644 --- a/includes/Action.php +++ b/includes/Action.php @@ -455,9 +455,10 @@ abstract class FormAction extends Action { /** * @see Action::execute() - * @throws ErrorPageError + * * @param $data array|null * @param $captureErrors bool + * @throws ErrorPageError|Exception * @return bool */ public function execute( array $data = null, $captureErrors = true ) { @@ -546,7 +547,7 @@ abstract class FormlessAction extends Action { * forms, they probably won't have any data, but some (eg rollback) may do * @param $data Array values that would normally be in the GET request * @param $captureErrors Bool whether to catch exceptions and just return false - * @throws ErrorPageError + * @throws ErrorPageError|Exception * @return Bool whether execution was successful */ public function execute( array $data = null, $captureErrors = true ) { diff --git a/includes/Hooks.php b/includes/Hooks.php index c9c06793f8..9e201a229a 100644 --- a/includes/Hooks.php +++ b/includes/Hooks.php @@ -138,6 +138,8 @@ class Hooks { * @param $event String: event name * @param $args Array: parameters passed to hook functions * + * @throws MWException + * @throws FatalError * @return Boolean True if no handler aborted the hook */ public static function run( $event, $args = array() ) { diff --git a/includes/LinksUpdate.php b/includes/LinksUpdate.php index a7a903e6e7..7ddf8638f9 100644 --- a/includes/LinksUpdate.php +++ b/includes/LinksUpdate.php @@ -819,6 +819,7 @@ class LinksDeletionUpdate extends SqlDataUpdate { * Constructor * * @param $page WikiPage Page we are updating + * @throws MWException */ function __construct( WikiPage $page ) { parent::__construct( false ); // no implicit transaction diff --git a/includes/Title.php b/includes/Title.php index 3b586c5edb..896218be29 100644 --- a/includes/Title.php +++ b/includes/Title.php @@ -675,6 +675,7 @@ class Title { /** * Get the page's content model id, see the CONTENT_MODEL_XXX constants. * + * @throws MWException * @return String: Content model id */ public function getContentModel() { @@ -2972,6 +2973,7 @@ class Title { * What is the page_latest field for this page? * * @param $flags Int a bit field; may be Title::GAID_FOR_UPDATE to select for update + * @throws MWException * @return Int or 0 if the page doesn't exist */ public function getLatestRevID( $flags = 0 ) { diff --git a/includes/User.php b/includes/User.php index 507b254f69..28ff630047 100644 --- a/includes/User.php +++ b/includes/User.php @@ -3034,6 +3034,7 @@ class User { * so it is still advisable to make the call conditional on isLoggedIn(), * and to commit the transaction after calling. * + * @throws MWException * @return Status */ public function addToDatabase() { diff --git a/includes/UserMailer.php b/includes/UserMailer.php index 8d1ed6812f..8fb8c35667 100644 --- a/includes/UserMailer.php +++ b/includes/UserMailer.php @@ -517,6 +517,8 @@ class EmailNotification { * @param $minorEdit bool * @param $oldid int Revision ID * @param $watchers array of user IDs + * @param string $pageStatus + * @throws MWException */ public function actuallyNotifyOnPageChange( $editor, $title, $timestamp, $summary, $minorEdit, $oldid, $watchers, $pageStatus = 'changed' ) { diff --git a/includes/WebRequest.php b/includes/WebRequest.php index e251ac5bb5..43d90b77b8 100644 --- a/includes/WebRequest.php +++ b/includes/WebRequest.php @@ -1044,6 +1044,7 @@ HTML; * * @since 1.19 * + * @throws MWException * @return String */ protected function getRawIP() { diff --git a/includes/WikiPage.php b/includes/WikiPage.php index 0b588cba3a..68068a8173 100644 --- a/includes/WikiPage.php +++ b/includes/WikiPage.php @@ -1409,6 +1409,7 @@ class WikiPage extends Page implements IDBAccessObject { * @param $text String: new text of the section * @param $sectionTitle String: new section's subject, only if $section is 'new' * @param $edittime String: revision timestamp or null to use the current revision + * @throws MWException * @return String new complete article text, or null if error * * @deprecated since 1.21, use replaceSectionContent() instead @@ -1451,6 +1452,7 @@ class WikiPage extends Page implements IDBAccessObject { * @param $sectionTitle String: new section's subject, only if $section is 'new' * @param $edittime String: revision timestamp or null to use the current revision * + * @throws MWException * @return Content new complete article content, or null if error * * @since 1.21 @@ -1599,10 +1601,11 @@ class WikiPage extends Page implements IDBAccessObject { * edit-already-exists error will be returned. These two conditions are also possible with * auto-detection due to MediaWiki's performance-optimised locking strategy. * - * @param $baseRevId the revision ID this edit was based off, if any + * @param bool|\the $baseRevId the revision ID this edit was based off, if any * @param $user User the user doing the edit * @param $serialisation_format String: format for storing the content in the database * + * @throws MWException * @return Status object. Possible errors: * edit-hook-aborted: The ArticleSave hook aborted the edit but didn't set the fatal flag of $status * edit-gone-missing: In update mode, but the article didn't exist diff --git a/includes/cache/MessageCache.php b/includes/cache/MessageCache.php index f5feaf9b04..d567035e40 100644 --- a/includes/cache/MessageCache.php +++ b/includes/cache/MessageCache.php @@ -257,7 +257,8 @@ class MessageCache { * or false if populating empty cache fails. Also returns true if MessageCache * is disabled. * - * @param $code String: language to which load messages + * @param bool|String $code String: language to which load messages + * @throws MWException * @return bool */ function load( $code = false ) { diff --git a/includes/content/ContentHandler.php b/includes/content/ContentHandler.php index 7d1be2b39c..282a7bae66 100644 --- a/includes/content/ContentHandler.php +++ b/includes/content/ContentHandler.php @@ -131,6 +131,7 @@ abstract class ContentHandler { * @param $format null|string the format to use for deserialization. If not * given, the model's default format is used. * + * @throws MWException * @return Content a Content object representing $text * * @throw MWException if $model or $format is not supported or if $text can diff --git a/includes/db/Database.php b/includes/db/Database.php index a638540232..ffc4de0a0b 100644 --- a/includes/db/Database.php +++ b/includes/db/Database.php @@ -780,6 +780,7 @@ abstract class DatabaseBase implements DatabaseType { * Closes a database connection. * if it is open : commits any open transactions * + * @throws MWException * @return Bool operation success. true if already closed. */ public function close() { @@ -3280,6 +3281,7 @@ abstract class DatabaseBase implements DatabaseType { * generated dynamically using $filename * @param bool|callable $inputCallback Callback: Optional function called for each complete line sent * @throws MWException + * @throws Exception|MWException * @return bool|string */ public function sourceFile( diff --git a/includes/filebackend/SwiftFileBackend.php b/includes/filebackend/SwiftFileBackend.php index e9d27f70fa..f4457dea6b 100644 --- a/includes/filebackend/SwiftFileBackend.php +++ b/includes/filebackend/SwiftFileBackend.php @@ -1318,8 +1318,9 @@ class SwiftFileBackend extends FileBackendStore { /** * Get an authenticated connection handle to the Swift proxy * - * @return CF_Connection|bool False on failure * @throws CloudFilesException + * @throws CloudFilesException|Exception + * @return CF_Connection|bool False on failure */ protected function getConnection() { if ( $this->connException instanceof CloudFilesException ) { diff --git a/includes/job/JobQueue.php b/includes/job/JobQueue.php index e88441d94d..19cecb7e2e 100644 --- a/includes/job/JobQueue.php +++ b/includes/job/JobQueue.php @@ -117,6 +117,7 @@ abstract class JobQueue { * * @param $jobs array List of Jobs * @param $flags integer Bitfield (supports JobQueue::QoS_Atomic) + * @throws MWException * @return bool */ final public function batchPush( array $jobs, $flags = 0 ) { @@ -165,6 +166,7 @@ abstract class JobQueue { * Acknowledge that a job was completed * * @param $job Job + * @throws MWException * @return bool */ final public function ack( Job $job ) { @@ -209,6 +211,7 @@ abstract class JobQueue { * previous "root job" for the same task of "update links of pages that use template X". * * @param $job Job + * @throws MWException * @return bool */ final public function deduplicateRootJob( Job $job ) { diff --git a/includes/job/JobQueueDB.php b/includes/job/JobQueueDB.php index e23ff0d905..fc2ea7dd95 100644 --- a/includes/job/JobQueueDB.php +++ b/includes/job/JobQueueDB.php @@ -58,6 +58,9 @@ class JobQueueDB extends JobQueue { /** * @see JobQueue::doBatchPush() + * @param array $jobs + * @param $flags + * @throws DBError|Exception * @return bool */ protected function doBatchPush( array $jobs, $flags ) { @@ -366,6 +369,8 @@ class JobQueueDB extends JobQueue { /** * @see JobQueue::doAck() + * @param Job $job + * @throws MWException * @return Job|bool */ protected function doAck( Job $job ) { @@ -385,6 +390,8 @@ class JobQueueDB extends JobQueue { /** * @see JobQueue::doDeduplicateRootJob() + * @param Job $job + * @throws MWException * @return bool */ protected function doDeduplicateRootJob( Job $job ) { diff --git a/includes/job/JobQueueGroup.php b/includes/job/JobQueueGroup.php index 97e0598a04..10fe51c740 100644 --- a/includes/job/JobQueueGroup.php +++ b/includes/job/JobQueueGroup.php @@ -76,6 +76,7 @@ class JobQueueGroup { * Insert jobs into the respective queues of with the belong * * @param $jobs Job|array A single Job or a list of Jobs + * @throws MWException * @return bool */ public function push( $jobs ) { diff --git a/includes/objectcache/SqlBagOStuff.php b/includes/objectcache/SqlBagOStuff.php index 54051dc18f..222d4751ea 100644 --- a/includes/objectcache/SqlBagOStuff.php +++ b/includes/objectcache/SqlBagOStuff.php @@ -86,6 +86,7 @@ class SqlBagOStuff extends BagOStuff { } /** + * @throws * @return DatabaseBase */ protected function getDB() { diff --git a/includes/site/SiteObject.php b/includes/site/SiteObject.php index 78c942b60b..217f860c61 100644 --- a/includes/site/SiteObject.php +++ b/includes/site/SiteObject.php @@ -151,6 +151,7 @@ class SiteObject extends ORMRow implements Site { * * @since 1.21 * + * @throws MWException * @return string|false */ public function getProtocol() { diff --git a/includes/specials/SpecialBooksources.php b/includes/specials/SpecialBooksources.php index 8e528dc3f6..6d27c1b981 100644 --- a/includes/specials/SpecialBooksources.php +++ b/includes/specials/SpecialBooksources.php @@ -130,6 +130,7 @@ class SpecialBookSources extends SpecialPage { * Determine where to get the list of book sources from, * format and output them * + * @throws MWException * @return string */ private function showList() { diff --git a/includes/specials/SpecialUndelete.php b/includes/specials/SpecialUndelete.php index 0d2ac7eb8d..08a758a383 100644 --- a/includes/specials/SpecialUndelete.php +++ b/includes/specials/SpecialUndelete.php @@ -432,9 +432,10 @@ class PageArchive { * be stuffed into old, otherwise the most recent will go into cur. * * @param $timestamps Array: pass an empty array to restore all revisions, otherwise list the ones to undelete. - * @param $comment String * @param $unsuppress Boolean: remove all ar_deleted/fa_deleted restrictions of seletected revs * + * @param $comment String + * @throws ReadOnlyError * @return Status, containing the number of revisions restored on success */ private function undeleteRevisions( $timestamps, $unsuppress = false, $comment = '' ) { -- 2.20.1