From: Aaron <aschulz@wikimedia.org>
Date: Wed, 25 Apr 2012 20:47:09 +0000 (-0700)
Subject: [FileBackend] Some documentation and minor cleanups.
X-Git-Tag: 1.31.0-rc.0~23804^2
X-Git-Url: https://git.cyclocoop.org/admin/?a=commitdiff_plain;h=a2b9285634c9f72826c642d798dac763b3337f3c;p=lhc%2Fweb%2Fwiklou.git

[FileBackend] Some documentation and minor cleanups.

Change-Id: Ia5f01679c928a9053cfd05d26fe1a03b67dac433
---

diff --git a/includes/filerepo/backend/FileBackend.php b/includes/filerepo/backend/FileBackend.php
index f3b879a4dd..aea2cd988c 100644
--- a/includes/filerepo/backend/FileBackend.php
+++ b/includes/filerepo/backend/FileBackend.php
@@ -176,8 +176,9 @@ abstract class FileBackend {
 	 *                         contents as the new contents to be written there.
 	 *
 	 * $opts is an associative of boolean flags, including:
-	 * 'force'               : Errors that would normally cause a rollback do not.
-	 *                         The remaining operations are still attempted if any fail.
+	 * 'force'               : Operation precondition errors no longer trigger an abort.
+	 *                         Any remaining operations are still attempted. Unexpected
+	 *                         failures may still cause remaning operations to be aborted.
 	 * 'nonLocking'          : No locks are acquired for the operations.
 	 *                         This can increase performance for non-critical writes.
 	 *                         This has no effect unless the 'force' flag is set.
@@ -315,8 +316,8 @@ abstract class FileBackend {
 	 * otherwise safe from modification from other processes. Normally,
 	 * the file will be a new temp file, which should be adequate.
 	 * $params include:
-	 *     srcs          : ordered source storage paths (e.g. chunk1, chunk2, ...)
-	 *     dst           : file system path to 0-byte temp file
+	 *     srcs : ordered source storage paths (e.g. chunk1, chunk2, ...)
+	 *     dst  : file system path to 0-byte temp file
 	 *
 	 * @param $params Array Operation parameters
 	 * @return Status
@@ -572,7 +573,7 @@ abstract class FileBackend {
 	 *
 	 * $params include:
 	 *     dir     : storage directory
-	 *     topOnly : only return direct child directories of the directory
+	 *     topOnly : only return direct child dirs of the directory
 	 *
 	 * @return Traversable|Array|null Returns null on failure
 	 * @since 1.20
@@ -607,7 +608,7 @@ abstract class FileBackend {
 	 *
 	 * $params include:
 	 *     dir     : storage directory
-	 *     topOnly : only return direct child files of the directory
+	 *     topOnly : only return direct child files of the directory (@since 1.20)
 	 *
 	 * @return Traversable|Array|null Returns null on failure
 	 */
diff --git a/includes/filerepo/backend/FileBackendStore.php b/includes/filerepo/backend/FileBackendStore.php
index f7e4529fae..ba6271f8eb 100644
--- a/includes/filerepo/backend/FileBackendStore.php
+++ b/includes/filerepo/backend/FileBackendStore.php
@@ -685,7 +685,7 @@ abstract class FileBackendStore extends FileBackend {
 
 	/**
 	 * @see FileBackend::getDirectoryList()
-	 * @return Array|null|Traversable
+	 * @return Traversable|Array|null Returns null on failure
 	 */
 	final public function getDirectoryList( array $params ) {
 		list( $fullCont, $dir, $shard ) = $this->resolveStoragePath( $params['dir'] );
@@ -712,13 +712,13 @@ abstract class FileBackendStore extends FileBackend {
 	 * @param $container string Resolved container name
 	 * @param $dir string Resolved path relative to container
 	 * @param $params Array
-	 * @return Traversable|Array|null
+	 * @return Traversable|Array|null Returns null on failure
 	 */
 	abstract public function getDirectoryListInternal( $container, $dir, array $params );
 
 	/**
 	 * @see FileBackend::getFileList()
-	 * @return Array|null|Traversable
+	 * @return Traversable|Array|null Returns null on failure
 	 */
 	final public function getFileList( array $params ) {
 		list( $fullCont, $dir, $shard ) = $this->resolveStoragePath( $params['dir'] );
@@ -745,7 +745,7 @@ abstract class FileBackendStore extends FileBackend {
 	 * @param $container string Resolved container name
 	 * @param $dir string Resolved path relative to container
 	 * @param $params Array
-	 * @return Traversable|Array|null
+	 * @return Traversable|Array|null Returns null on failure
 	 */
 	abstract public function getFileListInternal( $container, $dir, array $params );
 
@@ -895,6 +895,7 @@ abstract class FileBackendStore extends FileBackend {
 	 * Move a cache entry to the top (such as when accessed)
 	 *
 	 * @param $path string Storage path
+	 * @return void
 	 */
 	protected function pingCache( $path ) {
 		if ( isset( $this->cache[$path] ) ) {
@@ -920,6 +921,7 @@ abstract class FileBackendStore extends FileBackend {
 	 * Move a cache entry to the top (such as when accessed)
 	 *
 	 * @param $path string Storage path
+	 * @return void
 	 */
 	protected function pingExpensiveCache( $path ) {
 		if ( isset( $this->expensiveCache[$path] ) ) {
@@ -1239,7 +1241,7 @@ abstract class FileBackendStoreShardListIterator implements Iterator {
 	 * @return bool
 	 */
 	public function valid() {
-		if ( $this->iter == null ) {
+		if ( $this->iter === null ) {
 			return false; // some failure?
 		} elseif ( is_array( $this->iter ) ) {
 			return ( current( $this->iter ) !== false ); // no paths can have this value
diff --git a/includes/filerepo/backend/SwiftFileBackend.php b/includes/filerepo/backend/SwiftFileBackend.php
index af5d693dd8..16a37dc68e 100644
--- a/includes/filerepo/backend/SwiftFileBackend.php
+++ b/includes/filerepo/backend/SwiftFileBackend.php
@@ -1007,7 +1007,11 @@ abstract class SwiftFileBackendList implements Iterator {
 	 * @return bool
 	 */
 	public function valid() {
-		return ( current( $this->bufferIter ) !== false ); // no paths can have this value
+		if ( $this->bufferIter === null ) {
+			return false; // some failure?
+		} else {
+			return ( current( $this->bufferIter ) !== false ); // no paths can have this value
+		}
 	}
 
 	/**
@@ -1018,7 +1022,7 @@ abstract class SwiftFileBackendList implements Iterator {
 	 * @param $after string|null
 	 * @param $limit integer
 	 * @param $params Array
-	 * @return Traversable|Array|null
+	 * @return Traversable|Array|null Returns null on failure
 	 */
 	abstract protected function pageFromList( $container, $dir, &$after, $limit, array $params );
 }
@@ -1037,7 +1041,7 @@ class SwiftFileBackendDirList extends SwiftFileBackendList {
 
 	/**
 	 * @see SwiftFileBackendList::pageFromList()
-	 * @return Array
+	 * @return Array|null
 	 */
 	protected function pageFromList( $container, $dir, &$after, $limit, array $params ) {
 		return $this->backend->getDirListPageInternal( $container, $dir, $after, $limit, $params );
@@ -1058,7 +1062,7 @@ class SwiftFileBackendFileList extends SwiftFileBackendList {
 
 	/**
 	 * @see SwiftFileBackendList::pageFromList()
-	 * @return Array
+	 * @return Array|null
 	 */
 	protected function pageFromList( $container, $dir, &$after, $limit, array $params ) {
 		return $this->backend->getFileListPageInternal( $container, $dir, $after, $limit, $params );