Merge "test: skip math parser tests when missing $wgTexvc"

[lhc/web/wiklou.git] / includes / media / MediaHandler.php

diff --git a/includes/media/MediaHandler.php b/includes/media/MediaHandler.php
index b368906..2e8d41d 100644 (file)
--- a/includes/media/MediaHandler.php
+++ b/includes/media/MediaHandler.php
@@ -78,7 +78,7 @@ abstract class MediaHandler {
        /**
         * Merge a parameter array into a string appropriate for inclusion in filenames
         *
-        * @param $params array
+        * @param $params array Array of parameters that have been through normaliseParams.
         */
        abstract function makeParamString( $params );
 
@@ -220,6 +220,7 @@ abstract class MediaHandler {
         * @param string $dstPath filesystem destination path
         * @param string $dstUrl destination URL to use in output HTML
         * @param array $params arbitrary set of parameters validated by $this->validateParam()
+        *   Note: These parameters have *not* gone through $this->normaliseParams()
         * @param $flags Integer: a bitfield, may contain self::TRANSFORM_LATER
         *
         * @return MediaTransformOutput
@@ -228,6 +229,10 @@ abstract class MediaHandler {
 
        /**
         * Get the thumbnail extension and MIME type for a given source MIME type
+        *
+        * @param String $ext Extension of original file
+        * @param String $mime Mime type of original file
+        * @param Array $params Handler specific rendering parameters
         * @return array thumbnail extension and MIME type
         */
        function getThumbType( $ext, $mime, $params = null ) {
@@ -327,18 +332,28 @@ abstract class MediaHandler {
         * Get an associative array of page dimensions
         * Currently "width" and "height" are understood, but this might be
         * expanded in the future.
-        * Returns false if unknown or if the document is not multi-page.
+        * Returns false if unknown.
+        *
+        * It is expected that handlers for paged media (e.g. DjVuHandler)
+        * will override this method so that it gives the correct results
+        * for each specific page of the file, using the $page argument.
+        *
+        * @note For non-paged media, use getImageSize.
         *
         * @param $image File
-        * @param $page Unused, left for backcompatibility?
-        * @return array
+        * @param $page What page to get dimensions of
+        * @return array|bool
         */
        function getPageDimensions( $image, $page ) {
                $gis = $this->getImageSize( $image, $image->getLocalRefPath() );
-               return array(
-                       'width' => $gis[0],
-                       'height' => $gis[1]
-               );
+               if ( $gis ) {
+                       return array(
+                               'width' => $gis[0],
+                               'height' => $gis[1]
+                       );
+               } else {
+                       return false;
+               }
        }
 
        /**
@@ -475,6 +490,8 @@ abstract class MediaHandler {
        }
 
        /**
+        * Used instead of getLongDesc if there is no handler registered for file.
+        *
         * @param $file File
         * @return string
         */
@@ -484,6 +501,8 @@ abstract class MediaHandler {
        }
 
        /**
+        * Short description. Shown on Special:Search results.
+        *
         * @param $file File
         * @return string
         */
@@ -494,6 +513,8 @@ abstract class MediaHandler {
        }
 
        /**
+        * Long description. Shown under image on image description page surounded by ().
+        *
         * @param $file File
         * @return string
         */
@@ -503,6 +524,8 @@ abstract class MediaHandler {
        }
 
        /**
+        * Used instead of getShortDesc if there is no handler registered for file.
+        *
         * @param $file File
         * @return string
         */
@@ -530,12 +553,25 @@ abstract class MediaHandler {
                }
        }
 
+       /**
+        * Shown in file history box on image description page.
+        *
+        * @param File $file
+        * @return String Dimensions
+        */
        function getDimensionsString( $file ) {
                return '';
        }
 
        /**
-        * Modify the parser object post-transform
+        * Modify the parser object post-transform.
+        *
+        * This is often used to do $parser->addOutputHook(),
+        * in order to add some javascript to render a viewer.
+        * See TimedMediaHandler or OggHandler for an example.
+        *
+        * @param Parser $parser
+        * @param File $file
         */
        function parserTransformHook( $parser, $file ) {}
 
@@ -583,10 +619,17 @@ abstract class MediaHandler {
        }
 
        /**
-        * Remove files from the purge list
+        * Remove files from the purge list.
+        *
+        * This is used by some video handlers to prevent ?action=purge
+        * from removing a transcoded video, which is expensive to
+        * regenerate.
+        *
+        * @see LocalFile::purgeThumbnails
         *
         * @param array $files
-        * @param array $options
+        * @param array $options Purge options. Currently will always be
+        *  an array with a single key 'forThumbRefresh' set to true.
         */
        public function filterThumbnailPurgeList( &$files, $options ) {
                // Do nothing