From 76b5f4c7a769df88768ed9b055d75485b2207788 Mon Sep 17 00:00:00 2001
From: Aaron Schulz <aschulz@wikimedia.org>
Date: Thu, 21 Feb 2013 11:45:51 -0800
Subject: [PATCH] Various job queue documentation tweaks.

Change-Id: I2fcd2470f4e9e29d44cccc9e4d82d0380fe48434
---
 includes/job/JobQueue.php      |  6 +++++-
 includes/job/JobQueueGroup.php | 15 +++++++++++++--
 2 files changed, 18 insertions(+), 3 deletions(-)

diff --git a/includes/job/JobQueue.php b/includes/job/JobQueue.php
index f02ed98a83..4996a9e7c2 100644
--- a/includes/job/JobQueue.php
+++ b/includes/job/JobQueue.php
@@ -164,6 +164,7 @@ abstract class JobQueue {
 	/**
 	 * Push a single jobs into the queue.
 	 * 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)
@@ -177,6 +178,7 @@ abstract class JobQueue {
 	/**
 	 * Push a batch of jobs into the queue.
 	 * 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 array List of Jobs
 	 * @param $flags integer Bitfield (supports JobQueue::QoS_Atomic)
@@ -208,6 +210,7 @@ abstract class JobQueue {
 	/**
 	 * Pop a job off of the queue.
 	 * This requires $wgJobClasses to be set for the given job type.
+	 * Outside callers should use JobQueueGroup::pop() instead of this function.
 	 *
 	 * @return Job|bool Returns false if there are no jobs
 	 * @throws MWException
@@ -238,6 +241,7 @@ abstract class JobQueue {
 	 * Acknowledge that a job was completed.
 	 *
 	 * 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
 	 * @return bool
@@ -382,6 +386,6 @@ abstract class JobQueue {
 	 * @throws MWException
 	 */
 	public function setTestingPrefix( $key ) {
-		throw new MWException( "Queue namespacing not support for this queue type." );
+		throw new MWException( "Queue namespacing not supported for this queue type." );
 	}
 }
diff --git a/includes/job/JobQueueGroup.php b/includes/job/JobQueueGroup.php
index 32c881f8ee..23a54949a9 100644
--- a/includes/job/JobQueueGroup.php
+++ b/includes/job/JobQueueGroup.php
@@ -75,8 +75,10 @@ class JobQueueGroup {
 	}
 
 	/**
+	 * Get the job queue object for a given queue type
+	 *
 	 * @param $type string
-	 * @return JobQueue Job queue object for a given queue type
+	 * @return JobQueue
 	 */
 	public function get( $type ) {
 		global $wgJobTypeConf;
@@ -93,7 +95,9 @@ class JobQueueGroup {
 
 	/**
 	 * Insert jobs into the respective queues of with the belong.
-	 * This inserts the jobs into the queue specified by $wgJobTypeConf.
+	 *
+	 * 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
 	 * @throws MWException
@@ -133,6 +137,9 @@ class JobQueueGroup {
 	/**
 	 * Pop a job off one of the job queues
 	 *
+	 * 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
 	 * @return Job|bool Returns false on failure
@@ -283,6 +290,10 @@ class JobQueueGroup {
 		return $count;
 	}
 
+	/**
+	 * @param $name string
+	 * @return mixed
+	 */
 	private function getCachedConfigVar( $name ) {
 		global $wgConf, $wgMemc;
 
-- 
2.20.1