From 6f8342ed2943e254e89d3a3a0fa08534e04e2b00 Mon Sep 17 00:00:00 2001
From: Brian Wolff <bawolff+wn@gmail.com>
Date: Thu, 19 Jun 2014 21:16:28 -0300
Subject: [PATCH] Some doc fixes to MediaHandler. No code changes

Change-Id: I2d79fce7aa55b9a0f2988c09a55594db4e8849f1
---
 includes/media/MediaHandler.php | 27 ++++++++++++++++++++++-----
 1 file changed, 22 insertions(+), 5 deletions(-)

diff --git a/includes/media/MediaHandler.php b/includes/media/MediaHandler.php
index efc02fecc5..f6717cdb05 100644
--- 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 ) {
-- 
2.20.1