Merge "[FileBackend] Some documentation and minor cleanups."

diff --git a/includes/filerepo/backend/FileBackend.php b/includes/filerepo/backend/FileBackend.php
index 52baf1e..544c9c2 100644 (file)
--- 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
@@ -573,7 +574,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
@@ -608,7 +609,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 803f966..b87a69f 100644 (file)
--- a/includes/filerepo/backend/FileBackendStore.php
+++ b/includes/filerepo/backend/FileBackendStore.php
@@ -711,7 +711,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'] );
@@ -738,13 +738,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'] );
@@ -771,7 +771,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 );
 
@@ -933,6 +933,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] ) ) {
@@ -958,6 +959,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] ) ) {
@@ -1358,7 +1360,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 435931c..41d30dd 100644 (file)
--- a/includes/filerepo/backend/SwiftFileBackend.php
+++ b/includes/filerepo/backend/SwiftFileBackend.php
@@ -1048,7 +1048,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
+               }
        }
 
        /**
@@ -1059,7 +1063,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 );
 }
@@ -1078,7 +1082,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 );
@@ -1099,7 +1103,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 );