From: Aaron Schulz <aschulz@wikimedia.org>
Date: Wed, 24 Apr 2013 21:19:23 +0000 (-0700)
Subject: Clarified PoolCounter::execute() docs a bit.
X-Git-Tag: 1.31.0-rc.0~19882
X-Git-Url: https://git.cyclocoop.org/%27.%24link.%27?a=commitdiff_plain;h=f9f2e9701374dbae9a88bcf84d25bcf5061d1153;p=lhc%2Fweb%2Fwiklou.git

Clarified PoolCounter::execute() docs a bit.

Change-Id: Id37e11e9520381cccf917d71ea269c8a85334c58
---

diff --git a/includes/PoolCounter.php b/includes/PoolCounter.php
index 38c6f046bc..2dac9388c0 100644
--- a/includes/PoolCounter.php
+++ b/includes/PoolCounter.php
@@ -190,9 +190,19 @@ abstract class PoolCounterWork {
 	}
 
 	/**
-	 * Get the result of the work (whatever it is), or false.
+	 * Get the result of the work (whatever it is), or the result of the error() function.
+	 * This returns the result of the first applicable method that returns a non-false value,
+	 * where the methods are checked in the following order:
+	 *   - a) doWork()       : Applies if the work is exclusive or no another process
+	 *                         is doing it, and on the condition that either this process
+	 *                         successfully entered the pool or the pool counter is down.
+	 *   - b) doCachedWork() : Applies if the work is cacheable and this blocked on another
+	 *                         process which finished the work.
+	 *   - c) fallback()     : Applies for all remaining cases.
+	 * If these all fall through (by returning false), then the result of error() is returned.
+	 *
 	 * @param $skipcache bool
-	 * @return bool|mixed
+	 * @return mixed
 	 */
 	public function execute( $skipcache = false ) {
 		if ( $this->cacheable && !$skipcache ) {