From 963b3aa740ab448a814ec52fef6efa4a2fdfc12a Mon Sep 17 00:00:00 2001
From: Siebrand Mazeland <s.mazeland@xs4all.nl>
Date: Mon, 25 Nov 2013 18:12:42 +0100
Subject: [PATCH] Update documentation for job related classes

Change-Id: I9c2965fa633e1dce4e5e53526e664e67607dd557
---
 includes/job/Job.php                          | 19 +++--
 includes/job/JobQueue.php                     | 85 +++++++++++--------
 includes/job/JobQueueDB.php                   | 38 +++++----
 includes/job/JobQueueFederated.php            | 33 +++++--
 includes/job/JobQueueGroup.php                | 27 +++---
 includes/job/JobQueueRedis.php                | 56 ++++++------
 .../job/aggregator/JobQueueAggregator.php     |  5 +-
 .../aggregator/JobQueueAggregatorRedis.php    |  2 +-
 includes/job/jobs/DoubleRedirectJob.php       |  5 ++
 includes/job/jobs/DuplicateJob.php            |  2 +-
 includes/job/jobs/EnotifNotifyJob.php         |  2 +-
 includes/job/jobs/HTMLCacheUpdateJob.php      | 11 ++-
 includes/job/jobs/NullJob.php                 |  4 +-
 includes/job/jobs/RefreshLinksJob.php         | 20 ++---
 includes/job/jobs/UploadFromUrlJob.php        | 16 ++--
 15 files changed, 196 insertions(+), 129 deletions(-)

diff --git a/includes/job/Job.php b/includes/job/Job.php
index b1400de938..3f44a918ff 100644
--- a/includes/job/Job.php
+++ b/includes/job/Job.php
@@ -55,7 +55,7 @@ abstract class Job {
 
 	/**
 	 * Run the job
-	 * @return boolean success
+	 * @return bool Success
 	 */
 	abstract public function run();
 
@@ -67,7 +67,7 @@ abstract class Job {
 	 * Create the appropriate object to handle a specific job
 	 *
 	 * @param string $command Job command
-	 * @param $title Title: Associated title
+	 * @param Title $title Associated title
 	 * @param array|bool $params Job parameters
 	 * @param int $id Job identifier
 	 * @throws MWException
@@ -130,7 +130,7 @@ abstract class Job {
 	 * Pop a job off the front of the queue.
 	 * This is subject to $wgJobTypesExcludedFromDefaultQueue.
 	 *
-	 * @return Job or false if there's no jobs
+	 * @return Job|bool False if there are no jobs
 	 * @deprecated since 1.21
 	 */
 	public static function pop() {
@@ -153,11 +153,12 @@ abstract class Job {
 		$this->params = $params;
 		$this->id = $id;
 
-		$this->removeDuplicates = false; // expensive jobs may set this to true
+		// expensive jobs may set this to true
+		$this->removeDuplicates = false;
 	}
 
 	/**
-	 * @return integer May be 0 for jobs stored outside the DB
+	 * @return int May be 0 for jobs stored outside the DB
 	 * @deprecated since 1.22
 	 */
 	public function getId() {
@@ -186,7 +187,7 @@ abstract class Job {
 	}
 
 	/**
-	 * @return integer|null UNIX timestamp to delay running this job until, otherwise null
+	 * @return int|null UNIX timestamp to delay running this job until, otherwise null
 	 * @since 1.22
 	 */
 	public function getReleaseTimestamp() {
@@ -216,7 +217,7 @@ abstract class Job {
 	 * only checked if ignoreDuplicates() returns true, meaning that duplicate
 	 * jobs are supposed to be ignored.
 	 *
-	 * @return Array Map of key/values
+	 * @return array Map of key/values
 	 * @since 1.21
 	 */
 	public function getDeduplicationInfo() {
@@ -240,7 +241,7 @@ abstract class Job {
 	/**
 	 * @see JobQueue::deduplicateRootJob()
 	 * @param string $key A key that identifies the task
-	 * @return Array
+	 * @return array
 	 * @since 1.21
 	 */
 	public static function newRootJobParams( $key ) {
@@ -252,7 +253,7 @@ abstract class Job {
 
 	/**
 	 * @see JobQueue::deduplicateRootJob()
-	 * @return Array
+	 * @return array
 	 * @since 1.21
 	 */
 	public function getRootJobParams() {
diff --git a/includes/job/JobQueue.php b/includes/job/JobQueue.php
index b8a612cc08..8d93dc0449 100644
--- a/includes/job/JobQueue.php
+++ b/includes/job/JobQueue.php
@@ -29,12 +29,23 @@
  * @since 1.21
  */
 abstract class JobQueue {
-	protected $wiki; // string; wiki ID
-	protected $type; // string; job type
-	protected $order; // string; job priority for pop()
-	protected $claimTTL; // integer; seconds
-	protected $maxTries; // integer; maximum number of times to try a job
-	protected $checkDelay; // boolean; allow delayed jobs
+	/** @var string Wiki ID */
+	protected $wiki;
+
+	/** @var string Job type */
+	protected $type;
+
+	/** @var string Job priority for pop() */
+	protected $order;
+
+	/** @var int Time to live in seconds */
+	protected $claimTTL;
+
+	/** @var int Maximum number of times to try a job */
+	protected $maxTries;
+
+	/** @var bool Allow delayed jobs */
+	protected $checkDelay;
 
 	/** @var BagOStuff */
 	protected $dupCache;
@@ -44,7 +55,8 @@ abstract class JobQueue {
 	const ROOTJOB_TTL = 2419200; // integer; seconds to remember root jobs (28 days)
 
 	/**
-	 * @param $params array
+	 * @param array $params
+	 * @throws MWException
 	 */
 	protected function __construct( array $params ) {
 		$this->wiki = $params['wiki'];
@@ -93,7 +105,7 @@ abstract class JobQueue {
 	 *
 	 * Queue classes should throw an exception if they do not support the options given.
 	 *
-	 * @param $params array
+	 * @param array $params
 	 * @return JobQueue
 	 * @throws MWException
 	 */
@@ -142,7 +154,7 @@ abstract class JobQueue {
 	/**
 	 * Get the allowed queue orders for configuration validation
 	 *
-	 * @return Array Subset of (random, timestamp, fifo, undefined)
+	 * @return array Subset of (random, timestamp, fifo, undefined)
 	 */
 	abstract protected function supportedOrders();
 
@@ -156,7 +168,7 @@ abstract class JobQueue {
 	/**
 	 * Find out if delayed jobs are supported for configuration validation
 	 *
-	 * @return boolean Whether delayed jobs are supported
+	 * @return bool Whether delayed jobs are supported
 	 */
 	protected function supportsDelayedJobs() {
 		return false; // not implemented
@@ -194,7 +206,7 @@ abstract class JobQueue {
 	 *
 	 * If caching is used, this number might be out of date for a minute.
 	 *
-	 * @return integer
+	 * @return int
 	 * @throws JobQueueError
 	 */
 	final public function getSize() {
@@ -207,7 +219,7 @@ abstract class JobQueue {
 
 	/**
 	 * @see JobQueue::getSize()
-	 * @return integer
+	 * @return int
 	 */
 	abstract protected function doGetSize();
 
@@ -217,7 +229,7 @@ abstract class JobQueue {
 	 *
 	 * If caching is used, this number might be out of date for a minute.
 	 *
-	 * @return integer
+	 * @return int
 	 * @throws JobQueueError
 	 */
 	final public function getAcquiredCount() {
@@ -230,7 +242,7 @@ abstract class JobQueue {
 
 	/**
 	 * @see JobQueue::getAcquiredCount()
-	 * @return integer
+	 * @return int
 	 */
 	abstract protected function doGetAcquiredCount();
 
@@ -240,7 +252,7 @@ abstract class JobQueue {
 	 *
 	 * If caching is used, this number might be out of date for a minute.
 	 *
-	 * @return integer
+	 * @return int
 	 * @throws JobQueueError
 	 * @since 1.22
 	 */
@@ -254,7 +266,7 @@ abstract class JobQueue {
 
 	/**
 	 * @see JobQueue::getDelayedCount()
-	 * @return integer
+	 * @return int
 	 */
 	protected function doGetDelayedCount() {
 		return 0; // not implemented
@@ -266,7 +278,7 @@ abstract class JobQueue {
 	 *
 	 * If caching is used, this number might be out of date for a minute.
 	 *
-	 * @return integer
+	 * @return int
 	 * @throws JobQueueError
 	 */
 	final public function getAbandonedCount() {
@@ -279,7 +291,7 @@ abstract class JobQueue {
 
 	/**
 	 * @see JobQueue::getAbandonedCount()
-	 * @return integer
+	 * @return int
 	 */
 	protected function doGetAbandonedCount() {
 		return 0; // not implemented
@@ -290,8 +302,8 @@ abstract class JobQueue {
 	 * This does not require $wgJobClasses to be set for the given job type.
 	 * Outside callers should use JobQueueGroup::push() instead of this function.
 	 *
-	 * @param $jobs Job|Array
-	 * @param $flags integer Bitfield (supports JobQueue::QOS_ATOMIC)
+	 * @param Job|array $jobs A single job or an array of Jobs
+	 * @param int $flags Bitfield (supports JobQueue::QOS_ATOMIC)
 	 * @return bool Returns false on failure
 	 * @throws JobQueueError
 	 */
@@ -305,9 +317,9 @@ abstract class JobQueue {
 	 * Outside callers should use JobQueueGroup::push() instead of this function.
 	 *
 	 * @param array $jobs List of Jobs
-	 * @param $flags integer Bitfield (supports JobQueue::QOS_ATOMIC)
+	 * @param int $flags Bitfield (supports JobQueue::QOS_ATOMIC)
+	 * @throws MWException
 	 * @return bool Returns false on failure
-	 * @throws JobQueueError
 	 */
 	final public function batchPush( array $jobs, $flags = 0 ) {
 		if ( !count( $jobs ) ) {
@@ -333,6 +345,8 @@ abstract class JobQueue {
 
 	/**
 	 * @see JobQueue::batchPush()
+	 * @param array $jobs
+	 * @param $flags
 	 * @return bool
 	 */
 	abstract protected function doBatchPush( array $jobs, $flags );
@@ -342,8 +356,8 @@ abstract class JobQueue {
 	 * This requires $wgJobClasses to be set for the given job type.
 	 * Outside callers should use JobQueueGroup::pop() instead of this function.
 	 *
+	 * @throws MWException
 	 * @return Job|bool Returns false if there are no jobs
-	 * @throws JobQueueError
 	 */
 	final public function pop() {
 		global $wgJobClasses;
@@ -384,9 +398,9 @@ abstract class JobQueue {
 	 * This does nothing for certain queue classes or if "claimTTL" is not set.
 	 * Outside callers should use JobQueueGroup::ack() instead of this function.
 	 *
-	 * @param $job Job
+	 * @param Job $job
+	 * @throws MWException
 	 * @return bool
-	 * @throws JobQueueError
 	 */
 	final public function ack( Job $job ) {
 		if ( $job->getType() !== $this->type ) {
@@ -401,6 +415,7 @@ abstract class JobQueue {
 
 	/**
 	 * @see JobQueue::ack()
+	 * @param Job $job
 	 * @return bool
 	 */
 	abstract protected function doAck( Job $job );
@@ -432,9 +447,9 @@ abstract class JobQueue {
 	 *
 	 * This does nothing for certain queue classes.
 	 *
-	 * @param $job Job
+	 * @param Job $job
+	 * @throws MWException
 	 * @return bool
-	 * @throws JobQueueError
 	 */
 	final public function deduplicateRootJob( Job $job ) {
 		if ( $job->getType() !== $this->type ) {
@@ -449,7 +464,8 @@ abstract class JobQueue {
 
 	/**
 	 * @see JobQueue::deduplicateRootJob()
-	 * @param $job Job
+	 * @param Job $job
+	 * @throws MWException
 	 * @return bool
 	 */
 	protected function doDeduplicateRootJob( Job $job ) {
@@ -476,9 +492,9 @@ abstract class JobQueue {
 	/**
 	 * Check if the "root" job of a given job has been superseded by a newer one
 	 *
-	 * @param $job Job
+	 * @param Job $job
+	 * @throws MWException
 	 * @return bool
-	 * @throws JobQueueError
 	 */
 	final protected function isRootJobOldDuplicate( Job $job ) {
 		if ( $job->getType() !== $this->type ) {
@@ -537,6 +553,7 @@ abstract class JobQueue {
 
 	/**
 	 * @see JobQueue::delete()
+	 * @throws MWException
 	 * @return bool Success
 	 */
 	protected function doDelete() {
@@ -574,7 +591,7 @@ abstract class JobQueue {
 	 *   - callback : a PHP callable that performs the task
 	 *   - period   : the period in seconds corresponding to the task frequency
 	 *
-	 * @return Array
+	 * @return array
 	 */
 	final public function getPeriodicTasks() {
 		$tasks = $this->doGetPeriodicTasks();
@@ -587,7 +604,7 @@ abstract class JobQueue {
 
 	/**
 	 * @see JobQueue::getPeriodicTasks()
-	 * @return Array
+	 * @return array
 	 */
 	protected function doGetPeriodicTasks() {
 		return array();
@@ -697,7 +714,7 @@ abstract class JobQueue {
 	 *
 	 * @param string $key Event type
 	 * @param string $type Job type
-	 * @param integer $delta
+	 * @param int $delta
 	 * @since 1.22
 	 */
 	public static function incrStats( $key, $type, $delta = 1 ) {
@@ -708,7 +725,7 @@ abstract class JobQueue {
 	/**
 	 * Namespace the queue with a key to isolate it for testing
 	 *
-	 * @param $key string
+	 * @param string $key
 	 * @return void
 	 * @throws MWException
 	 */
diff --git a/includes/job/JobQueueDB.php b/includes/job/JobQueueDB.php
index 59d3de160c..b795695a9d 100644
--- a/includes/job/JobQueueDB.php
+++ b/includes/job/JobQueueDB.php
@@ -37,7 +37,8 @@ class JobQueueDB extends JobQueue {
 	/** @var BagOStuff */
 	protected $cache;
 
-	protected $cluster = false; // string; name of an external DB cluster
+	/** @var bool|string Name of an external DB cluster. False if not set */
+	protected $cluster = false;
 
 	/**
 	 * Additional parameters include:
@@ -45,7 +46,7 @@ class JobQueueDB extends JobQueue {
 	 *               If not specified, the primary DB cluster for the wiki will be used.
 	 *               This can be overridden with a custom cluster so that DB handles will
 	 *               be retrieved via LBFactory::getExternalLB() and getConnection().
-	 * @param $params array
+	 * @param array $params
 	 */
 	protected function __construct( array $params ) {
 		global $wgMemc;
@@ -94,7 +95,7 @@ class JobQueueDB extends JobQueue {
 
 	/**
 	 * @see JobQueue::doGetSize()
-	 * @return integer
+	 * @return int
 	 */
 	protected function doGetSize() {
 		$key = $this->getCacheKey( 'size' );
@@ -120,7 +121,7 @@ class JobQueueDB extends JobQueue {
 
 	/**
 	 * @see JobQueue::doGetAcquiredCount()
-	 * @return integer
+	 * @return int
 	 */
 	protected function doGetAcquiredCount() {
 		if ( $this->claimTTL <= 0 ) {
@@ -150,7 +151,7 @@ class JobQueueDB extends JobQueue {
 
 	/**
 	 * @see JobQueue::doGetAbandonedCount()
-	 * @return integer
+	 * @return int
 	 * @throws MWException
 	 */
 	protected function doGetAbandonedCount() {
@@ -209,12 +210,12 @@ class JobQueueDB extends JobQueue {
 	/**
 	 * This function should *not* be called outside of JobQueueDB
 	 *
-	 * @param DatabaseBase $dbw
+	 * @param IDatabase $dbw
 	 * @param array $jobs
 	 * @param int $flags
 	 * @param string $method
-	 * @return boolean
-	 * @throws type
+	 * @throws DBError
+	 * @return bool
 	 */
 	public function doBatchPushInternal( IDatabase $dbw, array $jobs, $flags, $method ) {
 		if ( !count( $jobs ) ) {
@@ -258,8 +259,11 @@ class JobQueueDB extends JobQueue {
 				$dbw->insert( 'job', $rowBatch, $method );
 			}
 			JobQueue::incrStats( 'job-insert', $this->type, count( $rows ) );
-			JobQueue::incrStats( 'job-insert-duplicate', $this->type,
-				count( $rowSet ) + count( $rowList ) - count( $rows ) );
+			JobQueue::incrStats(
+				'job-insert-duplicate',
+				$this->type,
+				count( $rowSet ) + count( $rowList ) - count( $rows )
+			);
 		} catch ( DBError $e ) {
 			if ( $flags & self::QOS_ATOMIC ) {
 				$dbw->rollback( $method );
@@ -336,7 +340,7 @@ class JobQueueDB extends JobQueue {
 	 * @param string $uuid 32 char hex string
 	 * @param $rand integer Random unsigned integer (31 bits)
 	 * @param bool $gte Search for job_random >= $random (otherwise job_random <= $random)
-	 * @return Row|false
+	 * @return stdClass|bool Row|false
 	 */
 	protected function claimRandom( $uuid, $rand, $gte ) {
 		$dbw = $this->getMasterDB();
@@ -386,6 +390,7 @@ class JobQueueDB extends JobQueue {
 					continue; // use job_random
 				}
 			}
+
 			if ( $row ) { // claim the job
 				$dbw->update( 'job', // update by PK
 					array(
@@ -412,7 +417,7 @@ class JobQueueDB extends JobQueue {
 	 * Reserve a row with a single UPDATE without holding row locks over RTTs...
 	 *
 	 * @param string $uuid 32 char hex string
-	 * @return Row|false
+	 * @return stdClass|bool Row|false
 	 */
 	protected function claimOldest( $uuid ) {
 		$dbw = $this->getMasterDB();
@@ -557,7 +562,7 @@ class JobQueueDB extends JobQueue {
 	}
 
 	/**
-	 * @return Array
+	 * @return array
 	 */
 	protected function doGetPeriodicTasks() {
 		return array(
@@ -639,7 +644,7 @@ class JobQueueDB extends JobQueue {
 	/**
 	 * Recycle or destroy any jobs that have been claimed for too long
 	 *
-	 * @return integer Number of jobs recycled/deleted
+	 * @return int Number of jobs recycled/deleted
 	 */
 	public function recycleAndDeleteStaleJobs() {
 		$now = time();
@@ -721,7 +726,7 @@ class JobQueueDB extends JobQueue {
 	}
 
 	/**
-	 * @param $job Job
+	 * @param Job $job
 	 * @return array
 	 */
 	protected function insertFields( Job $job ) {
@@ -745,6 +750,7 @@ class JobQueueDB extends JobQueue {
 	}
 
 	/**
+	 * @throws JobQueueConnectionError
 	 * @return DBConnRef
 	 */
 	protected function getSlaveDB() {
@@ -756,6 +762,7 @@ class JobQueueDB extends JobQueue {
 	}
 
 	/**
+	 * @throws JobQueueConnectionError
 	 * @return DBConnRef
 	 */
 	protected function getMasterDB() {
@@ -779,6 +786,7 @@ class JobQueueDB extends JobQueue {
 	}
 
 	/**
+	 * @param $property
 	 * @return string
 	 */
 	private function getCacheKey( $property ) {
diff --git a/includes/job/JobQueueFederated.php b/includes/job/JobQueueFederated.php
index f598d29ad0..589bed6e29 100644
--- a/includes/job/JobQueueFederated.php
+++ b/includes/job/JobQueueFederated.php
@@ -47,10 +47,10 @@
  * @since 1.22
  */
 class JobQueueFederated extends JobQueue {
-	/** @var Array (partition name => weight) reverse sorted by weight */
+	/** @var array (partition name => weight) reverse sorted by weight */
 	protected $partitionMap = array();
 
-	/** @var Array (partition name => JobQueue) reverse sorted by weight */
+	/** @var array (partition name => JobQueue) reverse sorted by weight */
 	protected $partitionQueues = array();
 
 	/** @var HashRing */
@@ -59,7 +59,8 @@ class JobQueueFederated extends JobQueue {
 	/** @var BagOStuff */
 	protected $cache;
 
-	protected $maxPartitionsTry; // integer; maximum number of partitions to try
+	/** @var int Maximum number of partitions to try */
+	protected $maxPartitionsTry;
 
 	const CACHE_TTL_SHORT = 30; // integer; seconds to cache info without re-validating
 	const CACHE_TTL_LONG = 300; // integer; seconds to cache info that is kept up to date
@@ -82,6 +83,7 @@ class JobQueueFederated extends JobQueue {
 	 *                          during failure, at the cost of added latency and somewhat
 	 *                          less reliable job de-duplication mechanisms.
 	 * @param array $params
+	 * @throws MWException
 	 */
 	protected function __construct( array $params ) {
 		parent::__construct( $params );
@@ -184,7 +186,7 @@ class JobQueueFederated extends JobQueue {
 	/**
 	 * @param string $type
 	 * @param string $method
-	 * @return integer
+	 * @return int
 	 */
 	protected function getCrossPartitionSum( $type, $method ) {
 		$key = $this->getCacheKey( $type );
@@ -228,7 +230,8 @@ class JobQueueFederated extends JobQueue {
 	/**
 	 * @param array $jobs
 	 * @param HashRing $partitionRing
-	 * @param integer $flags
+	 * @param int $flags
+	 * @throws JobQueueError
 	 * @return array List of Job object that could not be inserted
 	 */
 	protected function tryJobInsertions( array $jobs, HashRing &$partitionRing, $flags ) {
@@ -238,6 +241,7 @@ class JobQueueFederated extends JobQueue {
 		// to use a consistent hash to avoid allowing duplicate jobs per partition.
 		// When inserting a batch of de-duplicated jobs, QOS_ATOMIC is disregarded.
 		$uJobsByPartition = array(); // (partition name => job list)
+		/** @var Job $job */
 		foreach ( $jobs as $key => $job ) {
 			if ( $job->ignoreDuplicates() ) {
 				$sha1 = sha1( serialize( $job->getDeduplicationInfo() ) );
@@ -257,6 +261,7 @@ class JobQueueFederated extends JobQueue {
 
 		// Insert the de-duplicated jobs into the queues...
 		foreach ( $uJobsByPartition as $partition => $jobBatch ) {
+			/** @var JobQueue $queue */
 			$queue = $this->partitionQueues[$partition];
 			try {
 				$ok = $queue->doBatchPush( $jobBatch, $flags | self::QOS_ATOMIC );
@@ -316,6 +321,8 @@ class JobQueueFederated extends JobQueue {
 			if ( $partition === false ) {
 				break; // all partitions at 0 weight
 			}
+
+			/** @var JobQueue $queue */
 			$queue = $this->partitionQueues[$partition];
 			try {
 				$job = $queue->pop();
@@ -374,6 +381,7 @@ class JobQueueFederated extends JobQueue {
 	}
 
 	protected function doDelete() {
+		/** @var JobQueue $queue */
 		foreach ( $this->partitionQueues as $queue ) {
 			try {
 				$queue->doDelete();
@@ -384,6 +392,7 @@ class JobQueueFederated extends JobQueue {
 	}
 
 	protected function doWaitForBackups() {
+		/** @var JobQueue $queue */
 		foreach ( $this->partitionQueues as $queue ) {
 			try {
 				$queue->waitForBackups();
@@ -395,6 +404,7 @@ class JobQueueFederated extends JobQueue {
 
 	protected function doGetPeriodicTasks() {
 		$tasks = array();
+		/** @var JobQueue $queue */
 		foreach ( $this->partitionQueues as $partition => $queue ) {
 			foreach ( $queue->getPeriodicTasks() as $task => $def ) {
 				$tasks["{$partition}:{$task}"] = $def;
@@ -412,9 +422,12 @@ class JobQueueFederated extends JobQueue {
 			'delayedcount',
 			'abandonedcount'
 		);
+
 		foreach ( $types as $type ) {
 			$this->cache->delete( $this->getCacheKey( $type ) );
 		}
+
+		/** @var JobQueue $queue */
 		foreach ( $this->partitionQueues as $queue ) {
 			$queue->doFlushCaches();
 		}
@@ -422,6 +435,8 @@ class JobQueueFederated extends JobQueue {
 
 	public function getAllQueuedJobs() {
 		$iterator = new AppendIterator();
+
+		/** @var JobQueue $queue */
 		foreach ( $this->partitionQueues as $queue ) {
 			$iterator->append( $queue->getAllQueuedJobs() );
 		}
@@ -431,6 +446,8 @@ class JobQueueFederated extends JobQueue {
 
 	public function getAllDelayedJobs() {
 		$iterator = new AppendIterator();
+
+		/** @var JobQueue $queue */
 		foreach ( $this->partitionQueues as $queue ) {
 			$iterator->append( $queue->getAllDelayedJobs() );
 		}
@@ -445,6 +462,8 @@ class JobQueueFederated extends JobQueue {
 
 	protected function doGetSiblingQueuesWithJobs( array $types ) {
 		$result = array();
+
+		/** @var JobQueue $queue */
 		foreach ( $this->partitionQueues as $queue ) {
 			try {
 				$nonEmpty = $queue->doGetSiblingQueuesWithJobs( $types );
@@ -466,6 +485,8 @@ class JobQueueFederated extends JobQueue {
 
 	protected function doGetSiblingQueueSizes( array $types ) {
 		$result = array();
+
+		/** @var JobQueue $queue */
 		foreach ( $this->partitionQueues as $queue ) {
 			try {
 				$sizes = $queue->doGetSiblingQueueSizes( $types );
@@ -485,12 +506,14 @@ class JobQueueFederated extends JobQueue {
 	}
 
 	public function setTestingPrefix( $key ) {
+		/** @var JobQueue $queue */
 		foreach ( $this->partitionQueues as $queue ) {
 			$queue->setTestingPrefix( $key );
 		}
 	}
 
 	/**
+	 * @param $property
 	 * @return string
 	 */
 	private function getCacheKey( $property ) {
diff --git a/includes/job/JobQueueGroup.php b/includes/job/JobQueueGroup.php
index 70820d5a58..0203ac8415 100644
--- a/includes/job/JobQueueGroup.php
+++ b/includes/job/JobQueueGroup.php
@@ -28,13 +28,14 @@
  * @since 1.21
  */
 class JobQueueGroup {
-	/** @var Array */
+	/** @var array */
 	protected static $instances = array();
 
 	/** @var ProcessCacheLRU */
 	protected $cache;
 
-	protected $wiki; // string; wiki ID
+	/** @var string Wiki ID */
+	protected $wiki;
 
 	/** @var array Map of (bucket => (queue => JobQueue, types => list of types) */
 	protected $coalescedQueues;
@@ -58,7 +59,7 @@ class JobQueueGroup {
 	}
 
 	/**
-	 * @param string $wiki Wiki ID
+	 * @param bool|string $wiki Wiki ID
 	 * @return JobQueueGroup
 	 */
 	public static function singleton( $wiki = false ) {
@@ -82,7 +83,7 @@ class JobQueueGroup {
 	/**
 	 * Get the job queue object for a given queue type
 	 *
-	 * @param $type string
+	 * @param string $type
 	 * @return JobQueue
 	 */
 	public function get( $type ) {
@@ -104,7 +105,7 @@ class JobQueueGroup {
 	 * This inserts the jobs into the queue specified by $wgJobTypeConf
 	 * and updates the aggregate job queue information cache as needed.
 	 *
-	 * @param $jobs Job|array A single Job or a list of Jobs
+	 * @param Job|array $jobs A single Job or a list of Jobs
 	 * @throws MWException
 	 * @return bool
 	 */
@@ -145,8 +146,8 @@ class JobQueueGroup {
 	 * This pops a job off a queue as specified by $wgJobTypeConf and
 	 * updates the aggregate job queue information cache as needed.
 	 *
-	 * @param $qtype integer|string JobQueueGroup::TYPE_DEFAULT or type string
-	 * @param $flags integer Bitfield of JobQueueGroup::USE_* constants
+	 * @param int|string $qtype JobQueueGroup::TYPE_DEFAULT or type string
+	 * @param int $flags Bitfield of JobQueueGroup::USE_* constants
 	 * @return Job|bool Returns false on failure
 	 */
 	public function pop( $qtype = self::TYPE_DEFAULT, $flags = 0 ) {
@@ -195,7 +196,7 @@ class JobQueueGroup {
 	/**
 	 * Acknowledge that a job was completed
 	 *
-	 * @param $job Job
+	 * @param Job $job
 	 * @return bool
 	 */
 	public function ack( Job $job ) {
@@ -206,7 +207,7 @@ class JobQueueGroup {
 	 * Register the "root job" of a given job into the queue for de-duplication.
 	 * This should only be called right *after* all the new jobs have been inserted.
 	 *
-	 * @param $job Job
+	 * @param Job $job
 	 * @return bool
 	 */
 	public function deduplicateRootJob( Job $job ) {
@@ -255,7 +256,7 @@ class JobQueueGroup {
 	/**
 	 * Get the list of job types that have non-empty queues
 	 *
-	 * @return Array List of job types that have non-empty queues
+	 * @return array List of job types that have non-empty queues
 	 */
 	public function getQueuesWithJobs() {
 		$types = array();
@@ -278,7 +279,7 @@ class JobQueueGroup {
 	/**
 	 * Get the size of the queus for a list of job types
 	 *
-	 * @return Array Map of (job type => size)
+	 * @return array Map of (job type => size)
 	 */
 	public function getQueueSizes() {
 		$sizeMap = array();
@@ -331,7 +332,7 @@ class JobQueueGroup {
 	 * This is only used for performance, such as to avoid spamming
 	 * the queue with many sub-jobs before they actually get run.
 	 *
-	 * @param $type string
+	 * @param string $type
 	 * @return bool
 	 */
 	public function isQueueDeprioritized( $type ) {
@@ -357,7 +358,7 @@ class JobQueueGroup {
 	 * the defined run period. Concurrent calls to this function will cause tasks
 	 * to be attempted twice, so they may need their own methods of mutual exclusion.
 	 *
-	 * @return integer Number of tasks run
+	 * @return int Number of tasks run
 	 */
 	public function executeReadyPeriodicTasks() {
 		global $wgMemc;
diff --git a/includes/job/JobQueueRedis.php b/includes/job/JobQueueRedis.php
index 3bed28e382..e8c475d074 100644
--- a/includes/job/JobQueueRedis.php
+++ b/includes/job/JobQueueRedis.php
@@ -60,12 +60,16 @@ class JobQueueRedis extends JobQueue {
 	/** @var RedisConnectionPool */
 	protected $redisPool;
 
-	protected $server; // string; server address
-	protected $compression; // string; compression method to use
+	/** @var string Server address */
+	protected $server;
+
+	/** @var string Compression method to use */
+	protected $compression;
 
 	const MAX_AGE_PRUNE = 604800; // integer; seconds a job can live once claimed (7 days)
 
-	protected $key; // string; key to prefix the queue keys with (used for testing)
+	/** @var string Key to prefix the queue keys with (used for testing) */
+	protected $key;
 
 	/**
 	 * @params include:
@@ -108,7 +112,7 @@ class JobQueueRedis extends JobQueue {
 
 	/**
 	 * @see JobQueue::doGetSize()
-	 * @return integer
+	 * @return int
 	 * @throws MWException
 	 */
 	protected function doGetSize() {
@@ -122,8 +126,8 @@ class JobQueueRedis extends JobQueue {
 
 	/**
 	 * @see JobQueue::doGetAcquiredCount()
-	 * @return integer
-	 * @throws MWException
+	 * @return int
+	 * @throws JobQueueError
 	 */
 	protected function doGetAcquiredCount() {
 		if ( $this->claimTTL <= 0 ) {
@@ -143,8 +147,8 @@ class JobQueueRedis extends JobQueue {
 
 	/**
 	 * @see JobQueue::doGetDelayedCount()
-	 * @return integer
-	 * @throws MWException
+	 * @return int
+	 * @throws JobQueueError
 	 */
 	protected function doGetDelayedCount() {
 		if ( !$this->checkDelay ) {
@@ -160,8 +164,8 @@ class JobQueueRedis extends JobQueue {
 
 	/**
 	 * @see JobQueue::doGetAbandonedCount()
-	 * @return integer
-	 * @throws MWException
+	 * @return int
+	 * @throws JobQueueError
 	 */
 	protected function doGetAbandonedCount() {
 		if ( $this->claimTTL <= 0 ) {
@@ -180,7 +184,7 @@ class JobQueueRedis extends JobQueue {
 	 * @param array $jobs
 	 * @param $flags
 	 * @return bool
-	 * @throws MWException
+	 * @throws JobQueueError
 	 */
 	protected function doBatchPush( array $jobs, $flags ) {
 		// Convert the jobs into field maps (de-duplicated against each other)
@@ -234,7 +238,7 @@ class JobQueueRedis extends JobQueue {
 	/**
 	 * @param RedisConnRef $conn
 	 * @param array $items List of results from JobQueueRedis::getNewJobFields()
-	 * @return integer Number of jobs inserted (duplicates are ignored)
+	 * @return int Number of jobs inserted (duplicates are ignored)
 	 * @throws RedisException
 	 */
 	protected function pushBlobs( RedisConnRef $conn, array $items ) {
@@ -287,7 +291,7 @@ LUA;
 	/**
 	 * @see JobQueue::doPop()
 	 * @return Job|bool
-	 * @throws MWException
+	 * @throws JobQueueError
 	 */
 	protected function doPop() {
 		$job = false;
@@ -401,7 +405,7 @@ LUA;
 	 * @see JobQueue::doAck()
 	 * @param Job $job
 	 * @return Job|bool
-	 * @throws MWException
+	 * @throws MWException|JobQueueError
 	 */
 	protected function doAck( Job $job ) {
 		if ( !isset( $job->metadata['uuid'] ) ) {
@@ -445,7 +449,7 @@ LUA;
 	 * @see JobQueue::doDeduplicateRootJob()
 	 * @param Job $job
 	 * @return bool
-	 * @throws MWException
+	 * @throws MWException|JobQueueError
 	 */
 	protected function doDeduplicateRootJob( Job $job ) {
 		if ( !$job->hasRootJobParams() ) {
@@ -473,6 +477,7 @@ LUA;
 	 * @see JobQueue::doIsRootJobOldDuplicate()
 	 * @param Job $job
 	 * @return bool
+	 * @throws JobQueueError
 	 */
 	protected function doIsRootJobOldDuplicate( Job $job ) {
 		if ( !$job->hasRootJobParams() ) {
@@ -495,6 +500,7 @@ LUA;
 	/**
 	 * @see JobQueue::doDelete()
 	 * @return bool
+	 * @throws JobQueueError
 	 */
 	protected function doDelete() {
 		static $props = array( 'l-unclaimed', 'z-claimed', 'z-abandoned',
@@ -595,7 +601,7 @@ LUA;
 	 * @param $uid string
 	 * @param $conn RedisConnRef
 	 * @return Job|bool Returns false if the job does not exist
-	 * @throws MWException
+	 * @throws MWException|JobQueueError
 	 */
 	public function getJobFromUidInternal( $uid, RedisConnRef $conn ) {
 		try {
@@ -620,8 +626,8 @@ LUA;
 	/**
 	 * Release any ready delayed jobs into the queue
 	 *
-	 * @return integer Number of jobs released
-	 * @throws MWException
+	 * @return int Number of jobs released
+	 * @throws JobQueueError
 	 */
 	public function releaseReadyDelayedJobs() {
 		$count = 0;
@@ -657,8 +663,8 @@ LUA;
 	/**
 	 * Recycle or destroy any jobs that have been claimed for too long
 	 *
-	 * @return integer Number of jobs recycled/deleted
-	 * @throws MWException
+	 * @return int Number of jobs recycled/deleted
+	 * @throws MWException|JobQueueError
 	 */
 	public function recycleAndDeleteStaleJobs() {
 		if ( $this->claimTTL <= 0 ) { // sanity
@@ -732,7 +738,7 @@ LUA;
 	}
 
 	/**
-	 * @return Array
+	 * @return array
 	 */
 	protected function doGetPeriodicTasks() {
 		$tasks = array();
@@ -753,7 +759,7 @@ LUA;
 	}
 
 	/**
-	 * @param $job Job
+	 * @param Job $job
 	 * @return array
 	 */
 	protected function getNewJobFields( Job $job ) {
@@ -829,8 +835,8 @@ LUA;
 	/**
 	 * Get a connection to the server that handles all sub-queues for this queue
 	 *
-	 * @return Array (server name, Redis instance)
-	 * @throws MWException
+	 * @return RedisConnRef
+	 * @throws JobQueueConnectionError
 	 */
 	protected function getConnection() {
 		$conn = $this->redisPool->getConnection( $this->server );
@@ -845,7 +851,7 @@ LUA;
 	 * @param $server string
 	 * @param $conn RedisConnRef
 	 * @param $e RedisException
-	 * @throws MWException
+	 * @throws JobQueueError
 	 */
 	protected function throwRedisException( $server, RedisConnRef $conn, $e ) {
 		$this->redisPool->handleException( $server, $conn, $e );
diff --git a/includes/job/aggregator/JobQueueAggregator.php b/includes/job/aggregator/JobQueueAggregator.php
index 142b162cd6..8600eed903 100644
--- a/includes/job/aggregator/JobQueueAggregator.php
+++ b/includes/job/aggregator/JobQueueAggregator.php
@@ -38,6 +38,7 @@ abstract class JobQueueAggregator {
 	}
 
 	/**
+	 * @throws MWException
 	 * @return JobQueueAggregator
 	 */
 	final public static function singleton() {
@@ -107,7 +108,7 @@ abstract class JobQueueAggregator {
 	/**
 	 * Get the list of all of the queues with jobs
 	 *
-	 * @return Array (job type => (list of wiki IDs))
+	 * @return array (job type => (list of wiki IDs))
 	 */
 	final public function getAllReadyWikiQueues() {
 		wfProfileIn( __METHOD__ );
@@ -144,7 +145,7 @@ abstract class JobQueueAggregator {
 	 * Get all databases that have a pending job.
 	 * This poll all the queues and is this expensive.
 	 *
-	 * @return Array (job type => (list of wiki IDs))
+	 * @return array (job type => (list of wiki IDs))
 	 */
 	protected function findPendingWikiQueues() {
 		global $wgLocalDatabases;
diff --git a/includes/job/aggregator/JobQueueAggregatorRedis.php b/includes/job/aggregator/JobQueueAggregatorRedis.php
index ca8975af6e..057a5878e8 100644
--- a/includes/job/aggregator/JobQueueAggregatorRedis.php
+++ b/includes/job/aggregator/JobQueueAggregatorRedis.php
@@ -32,7 +32,7 @@ class JobQueueAggregatorRedis extends JobQueueAggregator {
 	/** @var RedisConnectionPool */
 	protected $redisPool;
 
-	/** @var Array List of Redis server addresses */
+	/** @var array List of Redis server addresses */
 	protected $servers;
 
 	/**
diff --git a/includes/job/jobs/DoubleRedirectJob.php b/includes/job/jobs/DoubleRedirectJob.php
index 24b55214d9..f5f0d6329a 100644
--- a/includes/job/jobs/DoubleRedirectJob.php
+++ b/includes/job/jobs/DoubleRedirectJob.php
@@ -81,6 +81,11 @@ class DoubleRedirectJob extends Job {
 		JobQueueGroup::singleton()->push( $jobs );
 	}
 
+	/**
+	 * @param Title $title
+	 * @param array|bool $params
+	 * @param int $id
+	 */
 	function __construct( $title, $params = false, $id = 0 ) {
 		parent::__construct( 'fixDoubleRedirect', $title, $params, $id );
 		$this->reason = $params['reason'];
diff --git a/includes/job/jobs/DuplicateJob.php b/includes/job/jobs/DuplicateJob.php
index b3f337114f..7e5bd3ca16 100644
--- a/includes/job/jobs/DuplicateJob.php
+++ b/includes/job/jobs/DuplicateJob.php
@@ -30,7 +30,7 @@ final class DuplicateJob extends Job {
 	/**
 	 * Callers should use DuplicateJob::newFromJob() instead
 	 *
-	 * @param $title Title
+	 * @param Title $title
 	 * @param array $params job parameters
 	 * @param $id Integer: job id
 	 */
diff --git a/includes/job/jobs/EnotifNotifyJob.php b/includes/job/jobs/EnotifNotifyJob.php
index 816b531609..97a7af6b39 100644
--- a/includes/job/jobs/EnotifNotifyJob.php
+++ b/includes/job/jobs/EnotifNotifyJob.php
@@ -38,7 +38,7 @@ class EnotifNotifyJob extends Job {
 			$editor = User::newFromId( $this->params['editorID'] );
 		// B/C, only the name might be given.
 		} else {
-			# FIXME: newFromName could return false on a badly configured wiki.
+			# @todo FIXME: newFromName could return false on a badly configured wiki.
 			$editor = User::newFromName( $this->params['editor'], false );
 		}
 		$enotif->actuallyNotifyOnPageChange(
diff --git a/includes/job/jobs/HTMLCacheUpdateJob.php b/includes/job/jobs/HTMLCacheUpdateJob.php
index 1dd77ede3c..8885e25a79 100644
--- a/includes/job/jobs/HTMLCacheUpdateJob.php
+++ b/includes/job/jobs/HTMLCacheUpdateJob.php
@@ -47,7 +47,11 @@ class HTMLCacheUpdateJob extends Job {
 	/** @var BacklinkCache */
 	protected $blCache;
 
-	protected $rowsPerJob, $rowsPerQuery;
+	/** @var int Number of rows to update per job, see $wgUpdateRowsPerJob */
+	protected $rowsPerJob;
+
+	/** @var int Number of rows to update per query, see $wgUpdateRowsPerQuery */
+	protected $rowsPerQuery;
 
 	/**
 	 * Construct a job
@@ -133,7 +137,7 @@ class HTMLCacheUpdateJob extends Job {
 	 * using a pre-calculated title array which gives the links in that range.
 	 * Queue the resulting jobs.
 	 *
-	 * @param array $titleArray
+	 * @param array|TitleArrayFromResult $titleArray
 	 * @param array $rootJobParams
 	 */
 	protected function insertJobsFromTitles( $titleArray, $rootJobParams = array() ) {
@@ -145,6 +149,7 @@ class HTMLCacheUpdateJob extends Job {
 		$jobs = array();
 		$start = $this->params['start']; # start of the current job
 		$numTitles = 0;
+		/** @var Title $title */
 		foreach ( $titleArray as $title ) {
 			$id = $title->getArticleID();
 			# $numTitles is now the number of titles in the current job not
@@ -213,7 +218,7 @@ class HTMLCacheUpdateJob extends Job {
 
 	/**
 	 * Invalidate an array (or iterator) of Title objects, right now
-	 * @param array $titleArray
+	 * @param array|TitleArrayFromResult $titleArray
 	 */
 	protected function invalidateTitles( $titleArray ) {
 		global $wgUseFileCache, $wgUseSquid;
diff --git a/includes/job/jobs/NullJob.php b/includes/job/jobs/NullJob.php
index 77f65728b0..f62419cbb0 100644
--- a/includes/job/jobs/NullJob.php
+++ b/includes/job/jobs/NullJob.php
@@ -46,9 +46,9 @@
  */
 class NullJob extends Job {
 	/**
-	 * @param $title Title (can be anything)
+	 * @param Title $title
 	 * @param array $params job parameters (lives, usleep)
-	 * @param $id Integer: job id
+	 * @param int $id Job id
 	 */
 	function __construct( $title, $params, $id = 0 ) {
 		parent::__construct( 'null', $title, $params, $id );
diff --git a/includes/job/jobs/RefreshLinksJob.php b/includes/job/jobs/RefreshLinksJob.php
index 377fea58e6..753e3f9385 100644
--- a/includes/job/jobs/RefreshLinksJob.php
+++ b/includes/job/jobs/RefreshLinksJob.php
@@ -34,7 +34,7 @@ class RefreshLinksJob extends Job {
 
 	/**
 	 * Run a refreshLinks job
-	 * @return boolean success
+	 * @return bool success
 	 */
 	function run() {
 		$linkCache = LinkCache::singleton();
@@ -67,7 +67,7 @@ class RefreshLinksJob extends Job {
 	}
 
 	/**
-	 * @return Array
+	 * @return array
 	 */
 	public function getDeduplicationInfo() {
 		$info = parent::getDeduplicationInfo();
@@ -80,9 +80,9 @@ class RefreshLinksJob extends Job {
 	}
 
 	/**
-	 * @param $title Title
-	 * @param $revision Revision
-	 * @param $fname string
+	 * @param Title $title
+	 * @param Revision $revision
+	 * @param string $fname
 	 * @return void
 	 */
 	public static function runForTitleInternal( Title $title, Revision $revision, $fname ) {
@@ -121,7 +121,7 @@ class RefreshLinksJob2 extends Job {
 
 	/**
 	 * Run a refreshLinks2 job
-	 * @return boolean success
+	 * @return bool success
 	 */
 	function run() {
 		global $wgUpdateRowsPerJob;
@@ -186,9 +186,9 @@ class RefreshLinksJob2 extends Job {
 	}
 
 	/**
-	 * @param $table string
-	 * @param $masterPos mixed
-	 * @return Array
+	 * @param string $table
+	 * @param mixed $masterPos
+	 * @return array
 	 */
 	protected function getSingleTitleJobs( $table, $masterPos ) {
 		# The "start"/"end" fields are not set for the base jobs
@@ -214,7 +214,7 @@ class RefreshLinksJob2 extends Job {
 	}
 
 	/**
-	 * @return Array
+	 * @return array
 	 */
 	public function getDeduplicationInfo() {
 		$info = parent::getDeduplicationInfo();
diff --git a/includes/job/jobs/UploadFromUrlJob.php b/includes/job/jobs/UploadFromUrlJob.php
index 1354169024..15d523f261 100644
--- a/includes/job/jobs/UploadFromUrlJob.php
+++ b/includes/job/jobs/UploadFromUrlJob.php
@@ -33,14 +33,10 @@
 class UploadFromUrlJob extends Job {
 	const SESSION_KEYNAME = 'wsUploadFromUrlJobData';
 
-	/**
-	 * @var UploadFromUrl
-	 */
+	/** @var UploadFromUrl */
 	public $upload;
 
-	/**
-	 * @var User
-	 */
+	/** @var User */
 	protected $user;
 
 	public function __construct( $title, $params, $id = 0 ) {
@@ -87,6 +83,8 @@ class UploadFromUrlJob extends Job {
 				# Stash the upload
 				$key = $this->upload->stashFile();
 
+				// @todo FIXME: This has been broken for a while.
+				// User::leaveUserMessage() does not exist.
 				if ( $this->params['leaveMessage'] ) {
 					$this->user->leaveUserMessage(
 						wfMessage( 'upload-warning-subj' )->text(),
@@ -121,17 +119,19 @@ class UploadFromUrlJob extends Job {
 	 * Leave a message on the user talk page or in the session according to
 	 * $params['leaveMessage'].
 	 *
-	 * @param $status Status
+	 * @param Status $status
 	 */
 	protected function leaveMessage( $status ) {
 		if ( $this->params['leaveMessage'] ) {
 			if ( $status->isGood() ) {
+				// @todo FIXME: user->leaveUserMessage does not exist.
 				$this->user->leaveUserMessage( wfMessage( 'upload-success-subj' )->text(),
 					wfMessage( 'upload-success-msg',
 						$this->upload->getTitle()->getText(),
 						$this->params['url']
 					)->text() );
 			} else {
+				// @todo FIXME: user->leaveUserMessage does not exist.
 				$this->user->leaveUserMessage( wfMessage( 'upload-failure-subj' )->text(),
 					wfMessage( 'upload-failure-msg',
 						$status->getWikiText(),
@@ -157,7 +157,7 @@ class UploadFromUrlJob extends Job {
 	 *
 	 * @param string $result the result (Success|Warning|Failure)
 	 * @param string $dataKey the key of the extra data
-	 * @param $dataValue Mixed: the extra data itself
+	 * @param mixed $dataValue The extra data itself
 	 */
 	protected function storeResultInSession( $result, $dataKey, $dataValue ) {
 		$session =& self::getSessionData( $this->params['sessionKey'] );
-- 
2.20.1