| Index: trunk/phase3/includes/upload/UploadStash.php |
| — | — | @@ -34,7 +34,8 @@ |
| 35 | 35 | /** |
| 36 | 36 | * Represents the session which contains temporarily stored files. |
| 37 | 37 | * Designed to be compatible with the session stashing code in UploadBase (should replace it eventually) |
| 38 | | - * @param {FileRepo} $repo: optional -- repo in which to store files. Will choose LocalRepo if not supplied. |
| | 38 | + * |
| | 39 | + * @param $repo FileRepo: optional -- repo in which to store files. Will choose LocalRepo if not supplied. |
| 39 | 40 | */ |
| 40 | 41 | public function __construct( $repo = null ) { |
| 41 | 42 | |
| — | — | @@ -56,20 +57,22 @@ |
| 57 | 58 | } |
| 58 | 59 | |
| 59 | 60 | /** |
| 60 | | - * Get the base of URLs by which one can access the files |
| 61 | | - * @return {String} url |
| | 61 | + * Get the base of URLs by which one can access the files |
| | 62 | + * |
| | 63 | + * @return String: url |
| 62 | 64 | */ |
| 63 | 65 | public function getBaseUrl() { |
| 64 | 66 | return $this->baseUrl; |
| 65 | 67 | } |
| 66 | 68 | |
| 67 | | - /** |
| | 69 | + /** |
| 68 | 70 | * Get a file and its metadata from the stash. |
| 69 | 71 | * May throw exception if session data cannot be parsed due to schema change, or key not found. |
| 70 | | - * @param {Integer} $key: key |
| | 72 | + * |
| | 73 | + * @param $key Integer: key |
| 71 | 74 | * @throws UploadStashFileNotFoundException |
| 72 | 75 | * @throws UploadStashBadVersionException |
| 73 | | - * @return {UploadStashItem} null if no such item or item out of date, or the item |
| | 76 | + * @return UploadStashItem: null if no such item or item out of date, or the item |
| 74 | 77 | */ |
| 75 | 78 | public function getFile( $key ) { |
| 76 | 79 | if ( ! preg_match( self::KEY_FORMAT_REGEX, $key ) ) { |
| — | — | @@ -104,12 +107,12 @@ |
| 105 | 108 | * We store data in a flat key-val namespace because that's how UploadBase did it. This also means we have to |
| 106 | 109 | * ensure that the key-val pairs in $data do not overwrite other required fields. |
| 107 | 110 | * |
| 108 | | - * @param {String} $path: path to file you want stashed |
| 109 | | - * @param {Array} $data: optional, other data you want associated with the file. Do not use 'mTempPath', 'mFileProps', 'mFileSize', or 'version' as keys here |
| 110 | | - * @param {String} $key: optional, unique key for this file in this session. Used for directory hashing when storing, otherwise not important |
| | 111 | + * @param $path String: path to file you want stashed |
| | 112 | + * @param $data Array: optional, other data you want associated with the file. Do not use 'mTempPath', 'mFileProps', 'mFileSize', or 'version' as keys here |
| | 113 | + * @param $key String: optional, unique key for this file in this session. Used for directory hashing when storing, otherwise not important |
| 111 | 114 | * @throws UploadStashBadPathException |
| 112 | 115 | * @throws UploadStashFileException |
| 113 | | - * @return {null|UploadStashFile} file, or null on failure |
| | 116 | + * @return UploadStashFile: file, or null on failure |
| 114 | 117 | */ |
| 115 | 118 | public function stashFile( $path, $data = array(), $key = null ) { |
| 116 | 119 | if ( ! file_exists( $path ) ) { |
| — | — | @@ -174,11 +177,12 @@ |
| 175 | 178 | /** |
| 176 | 179 | * A LocalFile wrapper around a file that has been temporarily stashed, so we can do things like create thumbnails for it |
| 177 | 180 | * Arguably UnregisteredLocalFile should be handling its own file repo but that class is a bit retarded currently |
| 178 | | - * @param {UploadStash} $stash: UploadStash, useful for obtaining config, stashing transformed files |
| 179 | | - * @param {FileRepo} $repo: repository where we should find the path |
| 180 | | - * @param {String} $path: path to file |
| 181 | | - * @param {String} $key: key to store the path and any stashed data under |
| 182 | | - * @param {String} $data: any other data we want stored with this file |
| | 181 | + * |
| | 182 | + * @param $stash UploadStash: useful for obtaining config, stashing transformed files |
| | 183 | + * @param $repo FileRepo: repository where we should find the path |
| | 184 | + * @param $path String: path to file |
| | 185 | + * @param $key String: key to store the path and any stashed data under |
| | 186 | + * @param $data String: any other data we want stored with this file |
| 183 | 187 | * @throws UploadStashBadPathException |
| 184 | 188 | * @throws UploadStashFileNotFoundException |
| 185 | 189 | */ |
| — | — | @@ -218,7 +222,8 @@ |
| 219 | 223 | * We do not necessarily care about doing the description at this point |
| 220 | 224 | * However, we also can't return the empty string, as the rest of MediaWiki demands this (and calls to imagemagick |
| 221 | 225 | * convert require it to be there) |
| 222 | | - * @return {String} dummy value |
| | 226 | + * |
| | 227 | + * @return String: dummy value |
| 223 | 228 | */ |
| 224 | 229 | public function getDescriptionUrl() { |
| 225 | 230 | return $this->getUrl(); |
| — | — | @@ -263,8 +268,8 @@ |
| 264 | 269 | * The actual argument is the result of thumbName although we seem to have |
| 265 | 270 | * buggy code elsewhere that expects a boolean 'suffix' |
| 266 | 271 | * |
| 267 | | - * @param {String|false} $thumbName: name of thumbnail (e.g. "120px-123456.jpg" ), or false to just get the path |
| 268 | | - * @return {String} path thumbnail should take on filesystem, or containing directory if thumbname is false |
| | 272 | + * @param $thumbName String: name of thumbnail (e.g. "120px-123456.jpg" ), or false to just get the path |
| | 273 | + * @return String: path thumbnail should take on filesystem, or containing directory if thumbname is false |
| 269 | 274 | */ |
| 270 | 275 | public function getThumbPath( $thumbName = false ) { |
| 271 | 276 | $path = dirname( $this->path ); |
| — | — | @@ -277,8 +282,8 @@ |
| 278 | 283 | /** |
| 279 | 284 | * Return the file/url base name of a thumbnail with the specified parameters |
| 280 | 285 | * |
| 281 | | - * @param {Array} $params: handler-specific parameters |
| 282 | | - * @return {String|null} base name for URL, like '120px-12345.jpg', or null if there is no handler |
| | 286 | + * @param $params Array: handler-specific parameters |
| | 287 | + * @return String: base name for URL, like '120px-12345.jpg', or null if there is no handler |
| 283 | 288 | */ |
| 284 | 289 | function thumbName( $params ) { |
| 285 | 290 | if ( !$this->getHandler() ) { |
| — | — | @@ -299,8 +304,8 @@ |
| 300 | 305 | * the thumbnail urls be predictable. However, in our model the URL is not based on the filename |
| 301 | 306 | * (that's hidden in the session) |
| 302 | 307 | * |
| 303 | | - * @param {String} $thumbName: basename of thumbnail file -- however, we don't want to use the file exactly |
| 304 | | - * @return {String} URL to access thumbnail, or URL with partial path |
| | 308 | + * @param $thumbName String: basename of thumbnail file -- however, we don't want to use the file exactly |
| | 309 | + * @return String: URL to access thumbnail, or URL with partial path |
| 305 | 310 | */ |
| 306 | 311 | public function getThumbUrl( $thumbName = false ) { |
| 307 | 312 | $path = $this->sessionStash->getBaseUrl(); |
| — | — | @@ -313,7 +318,8 @@ |
| 314 | 319 | /** |
| 315 | 320 | * The basename for the URL, which we want to not be related to the filename. |
| 316 | 321 | * Will also be used as the lookup key for a thumbnail file. |
| 317 | | - * @return {String} base url name, like '120px-123456.jpg' |
| | 322 | + * |
| | 323 | + * @return String: base url name, like '120px-123456.jpg' |
| 318 | 324 | */ |
| 319 | 325 | public function getUrlName() { |
| 320 | 326 | if ( ! $this->urlName ) { |
| — | — | @@ -324,8 +330,9 @@ |
| 325 | 331 | |
| 326 | 332 | /** |
| 327 | 333 | * Return the URL of the file, if for some reason we wanted to download it |
| 328 | | - * We tend not to do this for the original file, but we do want thumb icons |
| 329 | | - * @return {String} url |
| | 334 | + * We tend not to do this for the original file, but we do want thumb icons |
| | 335 | + * |
| | 336 | + * @return String: url |
| 330 | 337 | */ |
| 331 | 338 | public function getUrl() { |
| 332 | 339 | if ( !isset( $this->url ) ) { |
| — | — | @@ -338,7 +345,7 @@ |
| 339 | 346 | * Parent classes use this method, for no obvious reason, to return the path (relative to wiki root, I assume). |
| 340 | 347 | * But with this class, the URL is unrelated to the path. |
| 341 | 348 | * |
| 342 | | - * @return {String} url |
| | 349 | + * @return String: url |
| 343 | 350 | */ |
| 344 | 351 | public function getFullUrl() { |
| 345 | 352 | return $this->getUrl(); |
| — | — | @@ -347,7 +354,8 @@ |
| 348 | 355 | |
| 349 | 356 | /** |
| 350 | 357 | * Getter for session key (the session-unique id by which this file's location & metadata is stored in the session) |
| 351 | | - * @return {String} session key |
| | 358 | + * |
| | 359 | + * @return String: session key |
| 352 | 360 | */ |
| 353 | 361 | public function getSessionKey() { |
| 354 | 362 | return $this->sessionKey; |
| — | — | @@ -360,9 +368,9 @@ |
| 361 | 369 | * Here we override transform() to stash the thumbnail file, and then |
| 362 | 370 | * provide a way to get at the stashed thumbnail file to extract properties such as its URL |
| 363 | 371 | * |
| 364 | | - * @param {Array} $params: parameters suitable for File::transform() |
| 365 | | - * @param {Bitmask} $flags: flags suitable for File::transform() |
| 366 | | - * @return {ThumbnailImage} with additional File thumbnailFile property |
| | 372 | + * @param $params Array: parameters suitable for File::transform() |
| | 373 | + * @param $flags Integer: bitmask, flags suitable for File::transform() |
| | 374 | + * @return ThumbnailImage: with additional File thumbnailFile property |
| 367 | 375 | */ |
| 368 | 376 | public function transform( $params, $flags = 0 ) { |
| 369 | 377 | |
| — | — | @@ -390,7 +398,7 @@ |
| 391 | 399 | |
| 392 | 400 | /** |
| 393 | 401 | * Remove the associated temporary file |
| 394 | | - * @return {Status} success |
| | 402 | + * @return Status: success |
| 395 | 403 | */ |
| 396 | 404 | public function remove() { |
| 397 | 405 | return $this->repo->freeTemp( $this->path ); |