[FileBackend] Some documentation and minor cleanups.

Change-Id: Ia5f01679c928a9053cfd05d26fe1a03b67dac433

diff --git a/includes/filerepo/backend/FileBackend.php b/includes/filerepo/backend/FileBackend.php
index f3b879a..aea2cd9 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
@@ -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 f7e4529..ba6271f 100644 (file)
--- 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 af5d693..16a37dc 100644 (file)
--- 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 );