Minor bits of documentation updates to upload code

Including hint for bug 39195

Change-Id: I4cdab97011330c12a943112f6c05134362d26a82

diff --git a/includes/upload/UploadBase.php b/includes/upload/UploadBase.php
index 0e647a9..ba3a05c 100644 (file)
--- a/includes/upload/UploadBase.php
+++ b/includes/upload/UploadBase.php
@@ -63,6 +63,10 @@ abstract class UploadBase {
        const WINDOWS_NONASCII_FILENAME = 13;
        const FILENAME_TOO_LONG = 14;
 
+       /**
+        * @param $error int
+        * @return string
+        */
        public function getVerificationErrorCode( $error ) {
                $code_to_status = array(self::EMPTY_FILE => 'empty-file',
                                                                self::FILE_TOO_LARGE => 'file-too-large',
@@ -165,6 +169,7 @@ abstract class UploadBase {
 
        /**
         * Check whether a request if valid for this handler
+        * @param $request
         * @return bool
         */
        public static function isValidRequest( $request ) {
@@ -187,7 +192,7 @@ abstract class UploadBase {
         * @param $tempPath string the temporary path
         * @param $fileSize int the file size
         * @param $removeTempFile bool (false) remove the temporary file?
-        * @return null
+        * @throws MWException
         */
        public function initializePathInfo( $name, $tempPath, $fileSize, $removeTempFile = false ) {
                $this->mDesiredDestName = $name;
@@ -230,7 +235,7 @@ abstract class UploadBase {
 
        /**
         * @param $srcPath String: the source path
-        * @return stringthe real path if it was a virtual URL
+        * @return string the real path if it was a virtual URL
         */
        function getRealPath( $srcPath ) {
                wfProfileIn( __METHOD__ );
@@ -761,7 +766,7 @@ abstract class UploadBase {
        /**
         * Return the local file and initializes if necessary.
         *
-        * @return LocalFile
+        * @return LocalFile|null
         */
        public function getLocalFile() {
                if( is_null( $this->mLocalFile ) ) {
@@ -833,6 +838,7 @@ abstract class UploadBase {
         * earlier pseudo-'extensions' to determine type and execute
         * scripts, so the blacklist needs to check them all.
         *
+        * @param $filename string
         * @return array
         */
        public static function splitExtensions( $filename ) {
@@ -1031,6 +1037,10 @@ abstract class UploadBase {
                return false;
        }
 
+       /**
+        * @param $filename string
+        * @return bool
+        */
        protected function detectScriptInSvg( $filename ) {
                $check = new XmlTypeCheck( $filename, array( $this, 'checkSvgScriptCallback' ) );
                return $check->filterMatch;
@@ -1038,6 +1048,8 @@ abstract class UploadBase {
 
        /**
         * @todo Replace this with a whitelist filter!
+        * @param $element string
+        * @param $attribs array
         * @return bool
         */
        public function checkSvgScriptCallback( $element, $attribs ) {
@@ -1137,6 +1149,10 @@ abstract class UploadBase {
                return false; //No scripts detected
        }
 
+       /**
+        * @param $name string
+        * @return string
+        */
        private function stripXmlNamespace( $name ) {
                // 'http://www.w3.org/2000/svg:script' -> 'script'
                $parts = explode( ':', strtolower( $name ) );
@@ -1388,6 +1404,7 @@ abstract class UploadBase {
 
        /**
         * Helper function that checks whether the filename looks like a thumbnail
+        * @param $filename string
         * @return bool
         */
        public static function isThumbName( $filename ) {
@@ -1451,13 +1468,20 @@ abstract class UploadBase {
                return $info;
        }
 
-
+       /**
+        * @param $error array
+        * @return Status
+        */
        public function convertVerifyErrorToStatus( $error ) {
                $code = $error['status'];
                unset( $code['status'] );
                return Status::newFatal( $this->getVerificationErrorCode( $code ), $error );
        }
 
+       /**
+        * @param $forType null|string
+        * @return int
+        */
        public static function getMaxUploadSize( $forType = null ) {
                global $wgMaxUploadSize;
 

diff --git a/includes/upload/UploadFromChunks.php b/includes/upload/UploadFromChunks.php
index 87c798b..54a68af 100644 (file)
--- a/includes/upload/UploadFromChunks.php
+++ b/includes/upload/UploadFromChunks.php
@@ -29,10 +29,10 @@
  */
 class UploadFromChunks extends UploadFromFile {
        protected $mOffset, $mChunkIndex, $mFileKey, $mVirtualTempPath;
-       
+
        /**
         * Setup local pointers to stash, repo and user ( similar to UploadFromStash )
-        * 
+        *
         * @param $user User
         * @param $stash UploadStash
         * @param $repo FileRepo
@@ -82,7 +82,7 @@ class UploadFromChunks extends UploadFromFile {
                $this->updateChunkStatus();
                return $this->mLocalFile;
        }
-       
+
        /**
         * Continue chunk uploading
         */     
@@ -201,7 +201,7 @@ class UploadFromChunks extends UploadFromFile {
        private function updateChunkStatus(){
                wfDebug( __METHOD__ . " update chunk status for {$this->mFileKey} offset:" . 
                                        $this->getOffset() . ' inx:' . $this->getChunkIndex() . "\n" );
-               
+
                $dbw = $this->repo->getMasterDb();
                $dbw->update(
                        'uploadstash',
@@ -264,8 +264,9 @@ class UploadFromChunks extends UploadFromFile {
 
        /**
         * Output the chunk to disk
-        * 
+        *
         * @param $chunkPath string
+        * @throws UploadChunkFileException
         * @return FileRepoStatus
         */
        private function outputChunk( $chunkPath ){
@@ -291,6 +292,7 @@ class UploadFromChunks extends UploadFromFile {
                }
                return $storeStatus;
        }
+
        private function getChunkFileKey( $index = null ){
                if( $index === null ){
                        $index = $this->getChunkIndex();

diff --git a/includes/upload/UploadFromFile.php b/includes/upload/UploadFromFile.php
index fae9974..aa0cc77 100644 (file)
--- a/includes/upload/UploadFromFile.php
+++ b/includes/upload/UploadFromFile.php
@@ -36,26 +36,25 @@ class UploadFromFile extends UploadBase {
 
        /**
         * @param $request WebRequest
-        * @return null
         */
        function initializeFromRequest( &$request ) {
-               $upload = $request->getUpload( 'wpUploadFile' );                
+               $upload = $request->getUpload( 'wpUploadFile' );
                $desiredDestName = $request->getText( 'wpDestFile' );
-               if( !$desiredDestName )
+               if( !$desiredDestName ) {
                        $desiredDestName = $upload->getName();
-                       
-               return $this->initialize( $desiredDestName, $upload );
+               }
+
+               $this->initialize( $desiredDestName, $upload );
        }
 
        /**
         * Initialize from a filename and a WebRequestUpload
         * @param $name
         * @param $webRequestUpload
-        * @return null
         */
        function initialize( $name, $webRequestUpload ) {
                $this->mUpload = $webRequestUpload;
-               return $this->initializePathInfo( $name, 
+               $this->initializePathInfo( $name,
                        $this->mUpload->getTempName(), $this->mUpload->getSize() );
        }
 

diff --git a/includes/upload/UploadFromStash.php b/includes/upload/UploadFromStash.php
index d5cce14..607965f 100644 (file)
--- a/includes/upload/UploadFromStash.php
+++ b/includes/upload/UploadFromStash.php
@@ -62,8 +62,6 @@ class UploadFromStash extends UploadBase {
 
                        $this->stash = new UploadStash( $this->repo, $this->user );
                }
-
-               return true;
        }
 
        /**

diff --git a/includes/upload/UploadFromUrl.php b/includes/upload/UploadFromUrl.php
index a9e4519..c11d719 100644 (file)
--- a/includes/upload/UploadFromUrl.php
+++ b/includes/upload/UploadFromUrl.php
@@ -41,7 +41,7 @@ class UploadFromUrl extends UploadBase {
         *
         * @param $user User
         *
-        * @return true|string
+        * @return bool|string
         */
        public static function isAllowed( $user ) {
                if ( !$user->isAllowed( 'upload_by_url' ) ) {
@@ -92,6 +92,7 @@ class UploadFromUrl extends UploadBase {
         * @param $async mixed Whether the download should be performed
         * asynchronous. False for synchronous, async or async-leavemessage for
         * asynchronous download.
+        * @throws MWException
         */
        public function initialize( $name, $url, $async = false ) {
                global $wgAllowAsyncCopyUploads;
@@ -256,6 +257,7 @@ class UploadFromUrl extends UploadBase {
        /**
         * Wrapper around the parent function in order to defer checking protection
         * until we are sure that the file can actually be uploaded
+        * @param $user User
         * @return bool|mixed
         */
        public function verifyTitlePermissions( $user ) {
@@ -268,6 +270,10 @@ class UploadFromUrl extends UploadBase {
        /**
         * Wrapper around the parent function in order to defer uploading to the
         * job queue for asynchronous uploads
+        * @param $comment string
+        * @param $pageText string
+        * @param $watch bool
+        * @param $user User
         * @return Status
         */
        public function performUpload( $comment, $pageText, $watch, $user ) {
@@ -281,11 +287,11 @@ class UploadFromUrl extends UploadBase {
        }
 
        /**
-        * @param  $comment
-        * @param  $pageText
-        * @param  $watch
-        * @param  $user User
-        * @return
+        * @param $comment
+        * @param $pageText
+        * @param $watch
+        * @param $user User
+        * @return String
         */
        protected function insertJob( $comment, $pageText, $watch, $user ) {
                $sessionKey = $this->stashSession();