Some doc fixes to MediaHandler. No code changes

Change-Id: I2d79fce7aa55b9a0f2988c09a55594db4e8849f1

diff --git a/includes/media/MediaHandler.php b/includes/media/MediaHandler.php
index efc02fe..f6717cd 100644 (file)
--- a/includes/media/MediaHandler.php
+++ b/includes/media/MediaHandler.php
@@ -108,10 +108,20 @@ abstract class MediaHandler {
         * Get an image size array like that returned by getimagesize(), or false if it
         * can't be determined.
         *
+        * This function is used for determining the width, height and bitdepth directly
+        * from an image. The results are stored in the database in the img_width,
+        * img_height, img_bits fields.
+        *
+        * @note If this is a multipage file, return the width and height of the
+        *  first page.
+        *
         * @param File $image The image object, or false if there isn't one
         * @param string $path the filename
         * @return array Follow the format of PHP getimagesize() internal function.
-        *   See http://www.php.net/getimagesize
+        *   See http://www.php.net/getimagesize. MediaWiki will only ever use the
+        *   first two array keys (the width and height), and the 'bits' associative
+        *   key. All other array keys are ignored. Returning a 'bits' key is optional
+        *   as not all formats have a notion of "bitdepth".
         */
        abstract function getImageSize( $image, $path );
 
@@ -121,7 +131,7 @@ abstract class MediaHandler {
         * @param File $image The image object, or false if there isn't one.
         *   Warning, FSFile::getPropsFromPath might pass an (object)array() instead (!)
         * @param string $path The filename
-        * @return string
+        * @return string A string of metadata in php serialized form (Run through serialize())
         */
        function getMetadata( $image, $path ) {
                return '';
@@ -132,7 +142,7 @@ abstract class MediaHandler {
         *
         * This is not used for validating metadata, this is used for the api when returning
         * metadata, since api content formats should stay the same over time, and so things
-        * using ForiegnApiRepo can keep backwards compatibility
+        * using ForeignApiRepo can keep backwards compatibility
         *
         * All core media handlers share a common version number, and extensions can
         * use the GetMetadataVersion hook to append to the array (they should append a unique
@@ -175,6 +185,8 @@ abstract class MediaHandler {
 
        /**
         * Get a string describing the type of metadata, for display purposes.
+        *
+        * @note This method is currently unused.
         * @param File $image
         * @return string
         */
@@ -187,10 +199,15 @@ abstract class MediaHandler {
         * If it returns MediaHandler::METADATA_BAD (or false), Image
         * will reload the metadata from the file and update the database.
         * MediaHandler::METADATA_GOOD for if the metadata is a-ok,
-        * MediaHanlder::METADATA_COMPATIBLE if metadata is old but backwards
+        * MediaHandler::METADATA_COMPATIBLE if metadata is old but backwards
         * compatible (which may or may not trigger a metadata reload).
+        *
+        * @note Returning self::METADATA_BAD will trigger a metadata reload from
+        *  file on page view. Always returning this from a broken file, or suddenly
+        *  triggering as bad metadata for a large number of files can cause
+        *  performance problems.
         * @param File $image
-        * @param array $metadata
+        * @param string $metadata The metadata in serialized form
         * @return bool
         */
        function isMetadataValid( $image, $metadata ) {