From 37bc4ec3ddf5e3065ea3b22998e7f9b2db4ba1c7 Mon Sep 17 00:00:00 2001
From: Siebrand Mazeland <s.mazeland@xs4all.nl>
Date: Thu, 5 Dec 2013 20:27:27 +0100
Subject: [PATCH] Update documentation for media related classes

Change-Id: I7a9c8d59f88c68dc3835cb8a18f22a77cd7890fc
---
 includes/media/BMP.php                   |  10 +-
 includes/media/Bitmap.php                |  41 ++++----
 includes/media/BitmapMetadataHandler.php |  30 +++---
 includes/media/Bitmap_ClientOnly.php     |   8 +-
 includes/media/DjVu.php                  |  43 +++++---
 includes/media/DjVuImage.php             |  30 ++++--
 includes/media/Exif.php                  |  50 ++++------
 includes/media/ExifBitmap.php            |  10 +-
 includes/media/FormatMetadata.php        |  89 ++++++++---------
 includes/media/GIF.php                   |  11 ++-
 includes/media/GIFMetadataExtractor.php  |  14 +--
 includes/media/IPTC.php                  |   8 +-
 includes/media/ImageHandler.php          |  30 +++---
 includes/media/Jpeg.php                  |   3 +-
 includes/media/JpegMetadataExtractor.php |   9 +-
 includes/media/MediaHandler.php          | 119 +++++++++++++----------
 includes/media/MediaTransformOutput.php  |  28 +++---
 includes/media/PNG.php                   |  10 +-
 includes/media/PNGMetadataExtractor.php  |   6 +-
 includes/media/SVG.php                   |  46 +++++----
 includes/media/SVGMetadataExtractor.php  |  20 ++--
 includes/media/Tiff.php                  |  12 +--
 includes/media/XCF.php                   |  14 +--
 includes/media/XMP.php                   |  89 +++++++++--------
 includes/media/XMPInfo.php               |   6 +-
 includes/media/XMPValidate.php           |  52 +++++-----
 26 files changed, 431 insertions(+), 357 deletions(-)

diff --git a/includes/media/BMP.php b/includes/media/BMP.php
index 7271d993fd..967b01780f 100644
--- a/includes/media/BMP.php
+++ b/includes/media/BMP.php
@@ -29,7 +29,7 @@
  */
 class BmpHandler extends BitmapHandler {
 	/**
-	 * @param $file
+	 * @param File $file
 	 * @return bool
 	 */
 	function mustRender( $file ) {
@@ -39,9 +39,9 @@ class BmpHandler extends BitmapHandler {
 	/**
 	 * Render files as PNG
 	 *
-	 * @param $text
-	 * @param $mime
-	 * @param $params
+	 * @param string $text
+	 * @param string $mime
+	 * @param array $params
 	 * @return array
 	 */
 	function getThumbType( $text, $mime, $params = null ) {
@@ -52,7 +52,7 @@ class BmpHandler extends BitmapHandler {
 	 * Get width and height from the bmp header.
 	 *
 	 * @param $image
-	 * @param $filename
+	 * @param string $filename
 	 * @return array
 	 */
 	function getImageSize( $image, $filename ) {
diff --git a/includes/media/Bitmap.php b/includes/media/Bitmap.php
index 804393a241..13849f442a 100644
--- a/includes/media/Bitmap.php
+++ b/includes/media/Bitmap.php
@@ -28,7 +28,7 @@
  */
 class BitmapHandler extends ImageHandler {
 	/**
-	 * @param $image File
+	 * @param File $image
 	 * @param array $params Transform parameters. Entries with the keys 'width'
 	 * and 'height' are the respective screen width and height, while the keys
 	 * 'physicalWidth' and 'physicalHeight' indicate the thumbnail dimensions.
@@ -106,10 +106,10 @@ class BitmapHandler extends ImageHandler {
 	}
 
 	/**
-	 * @param $image File
-	 * @param  $dstPath
-	 * @param  $dstUrl
-	 * @param  $params
+	 * @param File $image
+	 * @param string $dstPath
+	 * @param string $dstUrl
+	 * @param array $params
 	 * @param int $flags
 	 * @return MediaTransformError|ThumbnailImage|TransformParameterError
 	 */
@@ -201,6 +201,7 @@ class BitmapHandler extends ImageHandler {
 		switch ( $scaler ) {
 			case 'hookaborted':
 				# Handled by the hook above
+				/** @var MediaTransformOutput $mto */
 				$err = $mto->isError() ? $mto : false;
 				break;
 			case 'im':
@@ -243,7 +244,9 @@ class BitmapHandler extends ImageHandler {
 	 * Returns which scaler type should be used. Creates parent directories
 	 * for $dstPath and returns 'client' on error
 	 *
-	 * @return string client,im,custom,gd
+	 * @param string $dstPath
+	 * @param bool $checkDstPath
+	 * @return string One of client, im, custom, gd, imext
 	 */
 	protected static function getScalerType( $dstPath, $checkDstPath = true ) {
 		global $wgUseImageResize, $wgUseImageMagick, $wgCustomConvertCommand;
@@ -272,11 +275,11 @@ class BitmapHandler extends ImageHandler {
 	 * Get a ThumbnailImage that respresents an image that will be scaled
 	 * client side
 	 *
-	 * @param $image File File associated with this thumbnail
+	 * @param File $image File associated with this thumbnail
 	 * @param array $scalerParams Array with scaler params
 	 * @return ThumbnailImage
 	 *
-	 * @todo fixme: no rotation support
+	 * @todo FIXME: No rotation support
 	 */
 	protected function getClientScalingThumbnailImage( $image, $scalerParams ) {
 		$params = array(
@@ -290,7 +293,7 @@ class BitmapHandler extends ImageHandler {
 	/**
 	 * Transform an image using ImageMagick
 	 *
-	 * @param $image File File associated with this thumbnail
+	 * @param File $image File associated with this thumbnail
 	 * @param array $params Array with scaler params
 	 *
 	 * @return MediaTransformError Error object if error occurred, false (=no error) otherwise
@@ -388,7 +391,7 @@ class BitmapHandler extends ImageHandler {
 	/**
 	 * Transform an image using the Imagick PHP extension
 	 *
-	 * @param $image File File associated with this thumbnail
+	 * @param File $image File associated with this thumbnail
 	 * @param array $params Array with scaler params
 	 *
 	 * @return MediaTransformError Error object if error occurred, false (=no error) otherwise
@@ -464,7 +467,7 @@ class BitmapHandler extends ImageHandler {
 	/**
 	 * Transform an image using a custom command
 	 *
-	 * @param $image File File associated with this thumbnail
+	 * @param File $image File associated with this thumbnail
 	 * @param array $params Array with scaler params
 	 *
 	 * @return MediaTransformError Error object if error occurred, false (=no error) otherwise
@@ -510,7 +513,7 @@ class BitmapHandler extends ImageHandler {
 	/**
 	 * Transform an image using the built in GD library
 	 *
-	 * @param $image File File associated with this thumbnail
+	 * @param File $image File associated with this thumbnail
 	 * @param array $params Array with scaler params
 	 *
 	 * @return MediaTransformError Error object if error occurred, false (=no error) otherwise
@@ -598,7 +601,8 @@ class BitmapHandler extends ImageHandler {
 	/**
 	 * Escape a string for ImageMagick's property input (e.g. -set -comment)
 	 * See InterpretImageProperties() in magick/property.c
-	 * @return mixed|string
+	 * @param string $s
+	 * @return string
 	 */
 	function escapeMagickProperty( $s ) {
 		// Double the backslashes
@@ -646,6 +650,8 @@ class BitmapHandler extends ImageHandler {
 	/**
 	 * Escape a string for ImageMagick's output filename. See
 	 * InterpretImageFilename() in magick/image.c.
+	 * @param string $path The file path
+	 * @param bool|string $scene The scene specification, or false if there is none
 	 * @return string
 	 */
 	function escapeMagickOutput( $path, $scene = false ) {
@@ -692,7 +698,7 @@ class BitmapHandler extends ImageHandler {
 	 * Retrieve the version of the installed ImageMagick
 	 * You can use PHPs version_compare() to use this value
 	 * Value is cached for one hour.
-	 * @return String representing the IM version.
+	 * @return string Representing the IM version.
 	 */
 	protected function getMagickVersion() {
 		global $wgMemc;
@@ -748,9 +754,9 @@ class BitmapHandler extends ImageHandler {
 	}
 
 	/**
-	 * @param $file File
+	 * @param File $file
 	 * @param array $params Rotate parameters.
-	 *    'rotation' clockwise rotation in degrees, allowed are multiples of 90
+	 *   'rotation' clockwise rotation in degrees, allowed are multiples of 90
 	 * @since 1.21
 	 * @return bool
 	 */
@@ -770,6 +776,7 @@ class BitmapHandler extends ImageHandler {
 				wfDebug( __METHOD__ . ": running ImageMagick: $cmd\n" );
 				wfProfileIn( 'convert' );
 				$retval = 0;
+				// @todo FIXME: Undefined variable %env
 				$err = wfShellExecWithStderr( $cmd, $retval, $env );
 				wfProfileOut( 'convert' );
 				if ( $retval !== 0 ) {
@@ -803,7 +810,7 @@ class BitmapHandler extends ImageHandler {
 	 * Rerurns whether the file needs to be rendered. Returns true if the
 	 * file requires rotation and we are able to rotate it.
 	 *
-	 * @param $file File
+	 * @param File $file
 	 * @return bool
 	 */
 	public function mustRender( $file ) {
diff --git a/includes/media/BitmapMetadataHandler.php b/includes/media/BitmapMetadataHandler.php
index 1e9419bf0f..2a393dbaa9 100644
--- a/includes/media/BitmapMetadataHandler.php
+++ b/includes/media/BitmapMetadataHandler.php
@@ -28,12 +28,14 @@
  * This sort of acts as an intermediary between MediaHandler::getMetadata
  * and the various metadata extractors.
  *
- * @todo other image formats.
+ * @todo Other image formats.
  * @ingroup Media
  */
 class BitmapMetadataHandler {
+	/** @var array */
 	private $metadata = array();
 
+	/** @var array Metadata priority */
 	private $metaPriority = array(
 		20 => array( 'other' ),
 		40 => array( 'native' ),
@@ -45,6 +47,7 @@ class BitmapMetadataHandler {
 		120 => array( 'exif' ),
 	);
 
+	/** @var string */
 	private $iptcType = 'iptc-no-hash';
 
 	/**
@@ -77,8 +80,8 @@ class BitmapMetadataHandler {
 	 *
 	 * Parameters are passed to the Exif class.
 	 *
-	 * @param $filename string
-	 * @param $byteOrder string
+	 * @param string $filename
+	 * @param string $byteOrder
 	 */
 	function getExif( $filename, $byteOrder ) {
 		global $wgShowEXIF;
@@ -95,7 +98,7 @@ class BitmapMetadataHandler {
 	 * doesn't have a priority, it will be silently discarded.
 	 *
 	 * @param array $metaArray array of metadata values
-	 * @param string $type type. defaults to other. if two things have the same type they're merged
+	 * @param string $type Type. defaults to other. if two things have the same type they're merged
 	 */
 	function addMetadata( $metaArray, $type = 'other' ) {
 		if ( isset( $this->metadata[$type] ) ) {
@@ -113,7 +116,7 @@ class BitmapMetadataHandler {
 	 *
 	 * This function is generally called by the media handlers' getMetadata()
 	 *
-	 * @return Array metadata array
+	 * @return array Metadata array
 	 */
 	function getMetadataArray() {
 		// this seems a bit ugly... This is all so its merged in right order
@@ -147,7 +150,7 @@ class BitmapMetadataHandler {
 	/** Main entry point for jpeg's.
 	 *
 	 * @param string $filename filename (with full path)
-	 * @return array metadata result array.
+	 * @return array Metadata result array.
 	 * @throws MWException on invalid file.
 	 */
 	static function Jpeg( $filename ) {
@@ -189,8 +192,8 @@ class BitmapMetadataHandler {
 	 * merge the png various tEXt chunks to that
 	 * are interesting, but for now it only does XMP
 	 *
-	 * @param string $filename full path to file
-	 * @return Array Array for storage in img_metadata.
+	 * @param string $filename Full path to file
+	 * @return array Array for storage in img_metadata.
 	 */
 	public static function PNG( $filename ) {
 		$showXMP = function_exists( 'xml_parser_create_ns' );
@@ -222,7 +225,7 @@ class BitmapMetadataHandler {
 	 * XMP and image comment.
 	 *
 	 * @param string $filename full path to file
-	 * @return Array metadata array
+	 * @return array Metadata array
 	 */
 	public static function GIF( $filename ) {
 
@@ -257,13 +260,12 @@ class BitmapMetadataHandler {
 	 * but needs some further processing because PHP's exif support
 	 * is stupid...)
 	 *
-	 * @todo Add XMP support, so this function actually makes
-	 * sense to put here.
+	 * @todo Add XMP support, so this function actually makes sense to put here.
 	 *
 	 * The various exceptions this throws are caught later.
-	 * @param $filename String
+	 * @param string $filename
 	 * @throws MWException
-	 * @return Array The metadata.
+	 * @return array The metadata.
 	 */
 	public static function Tiff( $filename ) {
 		if ( file_exists( $filename ) ) {
@@ -290,7 +292,7 @@ class BitmapMetadataHandler {
 	 * Little Endian or Big Endian. Needed for exif stuff.
 	 *
 	 * @param string $filename The filename
-	 * @return String 'BE' or 'LE' or false
+	 * @return string 'BE' or 'LE' or false
 	 */
 	static function getTiffByteOrder( $filename ) {
 		$fh = fopen( $filename, 'rb' );
diff --git a/includes/media/Bitmap_ClientOnly.php b/includes/media/Bitmap_ClientOnly.php
index ac751fe2cf..15ec794786 100644
--- a/includes/media/Bitmap_ClientOnly.php
+++ b/includes/media/Bitmap_ClientOnly.php
@@ -40,10 +40,10 @@ class BitmapHandler_ClientOnly extends BitmapHandler {
 	}
 
 	/**
-	 * @param $image File
-	 * @param  $dstPath
-	 * @param  $dstUrl
-	 * @param  $params
+	 * @param File $image
+	 * @param string $dstPath
+	 * @param string $dstUrl
+	 * @param array $params
 	 * @param int $flags
 	 * @return ThumbnailImage|TransformParameterError
 	 */
diff --git a/includes/media/DjVu.php b/includes/media/DjVu.php
index cbb3ec2ad5..7da5a4cc8d 100644
--- a/includes/media/DjVu.php
+++ b/includes/media/DjVu.php
@@ -42,7 +42,7 @@ class DjVuHandler extends ImageHandler {
 	}
 
 	/**
-	 * @param $file
+	 * @param File $file
 	 * @return bool
 	 */
 	function mustRender( $file ) {
@@ -50,7 +50,7 @@ class DjVuHandler extends ImageHandler {
 	}
 
 	/**
-	 * @param $file
+	 * @param File $file
 	 * @return bool
 	 */
 	function isMultiPage( $file ) {
@@ -68,8 +68,8 @@ class DjVuHandler extends ImageHandler {
 	}
 
 	/**
-	 * @param $name
-	 * @param $value
+	 * @param string $name
+	 * @param mixed $value
 	 * @return bool
 	 */
 	function validateParam( $name, $value ) {
@@ -85,7 +85,7 @@ class DjVuHandler extends ImageHandler {
 	}
 
 	/**
-	 * @param $params
+	 * @param array $params
 	 * @return bool|string
 	 */
 	function makeParamString( $params ) {
@@ -98,7 +98,7 @@ class DjVuHandler extends ImageHandler {
 	}
 
 	/**
-	 * @param $str
+	 * @param string $str
 	 * @return array|bool
 	 */
 	function parseParamString( $str ) {
@@ -111,7 +111,7 @@ class DjVuHandler extends ImageHandler {
 	}
 
 	/**
-	 * @param $params
+	 * @param array $params
 	 * @return array
 	 */
 	function getScriptParams( $params ) {
@@ -122,10 +122,10 @@ class DjVuHandler extends ImageHandler {
 	}
 
 	/**
-	 * @param $image File
-	 * @param  $dstPath
-	 * @param  $dstUrl
-	 * @param  $params
+	 * @param File $image
+	 * @param string $dstPath
+	 * @param string $dstUrl
+	 * @param array $params
 	 * @param int $flags
 	 * @return MediaTransformError|ThumbnailImage|TransformParameterError
 	 */
@@ -211,6 +211,8 @@ class DjVuHandler extends ImageHandler {
 	/**
 	 * Cache an instance of DjVuImage in an Image object, return that instance
 	 *
+	 * @param File $image
+	 * @param string $path
 	 * @return DjVuImage
 	 */
 	function getDjVuImage( $image, $path ) {
@@ -227,9 +229,9 @@ class DjVuHandler extends ImageHandler {
 
 	/**
 	 * Cache a document tree for the DjVu XML metadata
-	 * @param $image File
-	 * @param $gettext Boolean: DOCUMENT (Default: false)
-	 * @return bool
+	 * @param File $image
+	 * @param bool $gettext DOCUMENT (Default: false)
+	 * @return bool|SimpleXMLElement
 	 */
 	function getMetaTree( $image, $gettext = false ) {
 		if ( $gettext && isset( $image->djvuTextTree ) ) {
@@ -254,8 +256,11 @@ class DjVuHandler extends ImageHandler {
 			$image->djvuTextTree = false;
 			$tree = new SimpleXMLElement( $metadata );
 			if ( $tree->getName() == 'mw-djvu' ) {
+				/** @var SimpleXMLElement $b */
 				foreach ( $tree->children() as $b ) {
 					if ( $b->getName() == 'DjVuTxt' ) {
+						// @todo File::djvuTextTree and File::dejaMetaTree are declared
+						// dynamically. Add a public File::$data to facilitate this?
 						$image->djvuTextTree = $b;
 					} elseif ( $b->getName() == 'DjVuXML' ) {
 						$image->dejaMetaTree = $b;
@@ -276,6 +281,11 @@ class DjVuHandler extends ImageHandler {
 		}
 	}
 
+	/**
+	 * @param File $image
+	 * @param string $path
+	 * @return bool|array False on failure
+	 */
 	function getImageSize( $image, $path ) {
 		return $this->getDjVuImage( $image, $path )->getImageSize();
 	}
@@ -331,6 +341,11 @@ class DjVuHandler extends ImageHandler {
 		}
 	}
 
+	/**
+	 * @param File $image
+	 * @param int $page Page number to get information for
+	 * @return bool|string Page text or false when no text found.
+	 */
 	function getPageText( $image, $page ) {
 		$tree = $this->getMetaTree( $image, true );
 		if ( !$tree ) {
diff --git a/includes/media/DjVuImage.php b/includes/media/DjVuImage.php
index 9bfc378d08..71961061e1 100644
--- a/includes/media/DjVuImage.php
+++ b/includes/media/DjVuImage.php
@@ -34,6 +34,11 @@
  * @ingroup Media
  */
 class DjVuImage {
+	/**
+	 * @const DJVUTXT_MEMORY_LIMIT Memory limit for the DjVu description software
+	 */
+	const DJVUTXT_MEMORY_LIMIT = 300000;
+
 	/**
 	 * Constructor
 	 *
@@ -43,11 +48,6 @@ class DjVuImage {
 		$this->mFilename = $filename;
 	}
 
-	/**
-	 * @const DJVUTXT_MEMORY_LIMIT Memory limit for the DjVu description software
-	 */
-	const DJVUTXT_MEMORY_LIMIT = 300000;
-
 	/**
 	 * Check if the given file is indeed a valid DjVu image file
 	 * @return bool
@@ -87,6 +87,8 @@ class DjVuImage {
 		// @todo FIXME: Would be good to replace this extract() call with
 		// something that explicitly initializes local variables.
 		extract( unpack( 'a4magic/a4chunk/NchunkLength', $header ) );
+		/** @var string $chunk
+		 *  @var string $chunkLength */
 		echo "$chunk $chunkLength\n";
 		$this->dumpForm( $file, $chunkLength, 1 );
 		fclose( $file );
@@ -104,6 +106,8 @@ class DjVuImage {
 			// @todo FIXME: Would be good to replace this extract() call with
 			// something that explicitly initializes local variables.
 			extract( unpack( 'a4chunk/NchunkLength', $chunkHeader ) );
+			/** @var string $chunk
+			 *  @var string $chunkLength */
 			echo str_repeat( ' ', $indent * 4 ) . "$chunk $chunkLength\n";
 
 			if ( $chunk == 'FORM' ) {
@@ -138,6 +142,10 @@ class DjVuImage {
 			// something that explicitly initializes local variables.
 			extract( unpack( 'a4magic/a4form/NformLength/a4subtype', $header ) );
 
+			/** @var string $magic
+			 *  @var string $subtype
+			 *  @var string $formLength
+			 *  @var string $formType */
 			if ( $magic != 'AT&T' ) {
 				wfDebug( __METHOD__ . ": not a DjVu file\n" );
 			} elseif ( $subtype == 'DJVU' ) {
@@ -164,6 +172,8 @@ class DjVuImage {
 			// something that explicitly initializes local variables.
 			extract( unpack( 'a4chunk/Nlength', $header ) );
 
+			/** @var string $chunk
+			 *  @var string $length */
 			return array( $chunk, $length );
 		}
 	}
@@ -238,6 +248,13 @@ class DjVuImage {
 
 		# Newer files have rotation info in byte 10, but we don't use it yet.
 
+		/** @var string $width
+		 *  @var string $height
+		 *  @var string $major
+		 *  @var string $minor
+		 *  @var string $resolution
+		 *  @var string $length
+		 *  @var string $gamma */
 		return array(
 			'width' => $width,
 			'height' => $height,
@@ -311,7 +328,8 @@ EOR;
 
 	/**
 	 * Hack to temporarily work around djvutoxml bug
-	 * @return bool|string
+	 * @param $dump
+	 * @return string
 	 */
 	function convertDumpToXML( $dump ) {
 		if ( strval( $dump ) == '' ) {
diff --git a/includes/media/Exif.php b/includes/media/Exif.php
index e593fc8f87..bb5e344d94 100644
--- a/includes/media/Exif.php
+++ b/includes/media/Exif.php
@@ -101,15 +101,14 @@ class Exif {
 	/**
 	 * Constructor
 	 *
-	 * @param string $file filename.
+	 * @param string $file Filename.
 	 * @param string $byteOrder Type of byte ordering either 'BE' (Big Endian)
 	 *   or 'LE' (Little Endian). Default ''.
 	 * @throws MWException
 	 * @todo FIXME: The following are broke:
-	 * SubjectArea. Need to test the more obscure tags.
-	 *
-	 * DigitalZoomRatio = 0/0 is rejected. need to determine if that's valid.
-	 * possibly should treat 0/0 = 0. need to read exif spec on that.
+	 *   SubjectArea. Need to test the more obscure tags.
+	 *   DigitalZoomRatio = 0/0 is rejected. need to determine if that's valid.
+	 *   Possibly should treat 0/0 = 0. need to read exif spec on that.
 	 */
 	function __construct( $file, $byteOrder = '' ) {
 		/**
@@ -167,7 +166,7 @@ class Exif {
 
 			# Exif IFD Attribute Information (p30-31)
 			'EXIF' => array(
-				# TODO: NOTE: Nonexistence of this field is taken to mean nonconformance
+				# @todo NOTE: Nonexistence of this field is taken to mean nonconformance
 				# to the Exif 2.1 AND 2.2 standards
 				'ExifVersion' => Exif::UNDEFINED, # Exif version
 				'FlashPixVersion' => Exif::UNDEFINED, # Supported Flashpix version #p32
@@ -510,7 +509,7 @@ class Exif {
 	 * Convert an Exif::UNDEFINED from a raw binary string
 	 * to its value. This is sometimes needed depending on
 	 * the type of UNDEFINED field
-	 * @param string $prop name of property
+	 * @param string $prop Name of property
 	 */
 	private function exifPropToOrd( $prop ) {
 		if ( isset( $this->mFilteredExifData[$prop] ) ) {
@@ -521,7 +520,7 @@ class Exif {
 	/**
 	 * Convert gps in exif form to a single floating point number
 	 * for example 10 degress 20`40`` S -> -10.34444
-	 * @param string $prop a gps coordinate exif tag name (like GPSLongitude)
+	 * @param string $prop A GPS coordinate exif tag name (like GPSLongitude)
 	 */
 	private function exifGPStoNumber( $prop ) {
 		$loc =& $this->mFilteredExifData[$prop];
@@ -624,9 +623,7 @@ class Exif {
 	/**#@+
 	 * Validates if a tag value is of the type it should be according to the Exif spec
 	 *
-	 * @private
-	 *
-	 * @param $in Mixed: the input value to check
+	 * @param mixed $in The input value to check
 	 * @return bool
 	 */
 	private function isByte( $in ) {
@@ -642,7 +639,7 @@ class Exif {
 	}
 
 	/**
-	 * @param $in
+	 * @param mixed $in The input value to check
 	 * @return bool
 	 */
 	private function isASCII( $in ) {
@@ -666,7 +663,7 @@ class Exif {
 	}
 
 	/**
-	 * @param $in
+	 * @param mixed $in The input value to check
 	 * @return bool
 	 */
 	private function isShort( $in ) {
@@ -682,7 +679,7 @@ class Exif {
 	}
 
 	/**
-	 * @param $in
+	 * @param mixed $in The input value to check
 	 * @return bool
 	 */
 	private function isLong( $in ) {
@@ -698,7 +695,7 @@ class Exif {
 	}
 
 	/**
-	 * @param $in
+	 * @param mixed $in The input value to check
 	 * @return bool
 	 */
 	private function isRational( $in ) {
@@ -717,7 +714,7 @@ class Exif {
 	}
 
 	/**
-	 * @param $in
+	 * @param mixed $in The input value to check
 	 * @return bool
 	 */
 	private function isUndefined( $in ) {
@@ -727,7 +724,7 @@ class Exif {
 	}
 
 	/**
-	 * @param $in
+	 * @param mixed $in The input value to check
 	 * @return bool
 	 */
 	private function isSlong( $in ) {
@@ -743,7 +740,7 @@ class Exif {
 	}
 
 	/**
-	 * @param $in
+	 * @param mixed $in The input value to check
 	 * @return bool
 	 */
 	private function isSrational( $in ) {
@@ -766,11 +763,10 @@ class Exif {
 	/**
 	 * Validates if a tag has a legal value according to the Exif spec
 	 *
-	 * @private
 	 * @param string $section section where tag is located.
 	 * @param string $tag the tag to check.
-	 * @param $val Mixed: the value of the tag.
-	 * @param $recursive Boolean: true if called recursively for array types.
+	 * @param mixed $val The value of the tag.
+	 * @param bool $recursive True if called recursively for array types.
 	 * @return bool
 	 */
 	private function validate( $section, $tag, $val, $recursive = false ) {
@@ -850,11 +846,9 @@ class Exif {
 	/**
 	 * Convenience function for debugging output
 	 *
-	 * @private
-	 *
-	 * @param $in Mixed:
-	 * @param $fname String:
-	 * @param $action Mixed: , default NULL.
+	 * @param mixed $in Arrays will be processed with print_r().
+	 * @param string $fname Function name to log.
+	 * @param string|bool|null $action Default null.
 	 */
 	private function debug( $in, $fname, $action = null ) {
 		if ( !$this->log ) {
@@ -880,10 +874,8 @@ class Exif {
 	/**
 	 * Convenience function for debugging output
 	 *
-	 * @private
-	 *
 	 * @param string $fname the name of the function calling this function
-	 * @param $io Boolean: Specify whether we're beginning or ending
+	 * @param bool $io Specify whether we're beginning or ending
 	 */
 	private function debugFile( $fname, $io ) {
 		if ( !$this->log ) {
diff --git a/includes/media/ExifBitmap.php b/includes/media/ExifBitmap.php
index 0a14ca80fd..fe037b76f4 100644
--- a/includes/media/ExifBitmap.php
+++ b/includes/media/ExifBitmap.php
@@ -79,6 +79,11 @@ class ExifBitmapHandler extends BitmapHandler {
 		return $metadata;
 	}
 
+	/**
+	 * @param $image
+	 * @param array $metadata
+	 * @return bool|int
+	 */
 	function isMetadataValid( $image, $metadata ) {
 		global $wgShowEXIF;
 		if ( !$wgShowEXIF ) {
@@ -119,7 +124,7 @@ class ExifBitmapHandler extends BitmapHandler {
 	}
 
 	/**
-	 * @param $image File
+	 * @param File $image
 	 * @return array|bool
 	 */
 	function formatMetadata( $image ) {
@@ -214,8 +219,7 @@ class ExifBitmapHandler extends BitmapHandler {
 	 *
 	 * @param string $data
 	 * @return int 0, 90, 180 or 270
-	 * @todo FIXME orientation can include flipping as well; see if this is an
-	 * issue!
+	 * @todo FIXME: Orientation can include flipping as well; see if this is an issue!
 	 */
 	protected function getRotationForExif( $data ) {
 		if ( !$data ) {
diff --git a/includes/media/FormatMetadata.php b/includes/media/FormatMetadata.php
index fe8c4f4e1c..adaba76896 100644
--- a/includes/media/FormatMetadata.php
+++ b/includes/media/FormatMetadata.php
@@ -49,7 +49,7 @@
 class FormatMetadata extends ContextSource {
 	/**
 	 * Only output a single language for multi-language fields
-	 * @var boolean
+	 * @var bool
 	 * @since 1.23
 	 */
 	protected $singleLang = false;
@@ -57,7 +57,7 @@ class FormatMetadata extends ContextSource {
 	/**
 	 * Trigger only outputting single language for multilanguage fields
 	 *
-	 * @param Boolean $val
+	 * @param bool $val
 	 * @since 1.23
 	 */
 	public function setSingleLanguage( $val ) {
@@ -73,8 +73,8 @@ class FormatMetadata extends ContextSource {
 	 * This is the usual entry point for this class.
 	 *
 	 * @param array $tags the Exif data to format ( as returned by
-	 *                    Exif::getFilteredData() or BitmapMetadataHandler )
-	 * @param IContextSource $context Context to use (optional)
+	 *   Exif::getFilteredData() or BitmapMetadataHandler )
+	 * @param bool|IContextSource $context Context to use (optional)
 	 * @return array
 	 */
 	public static function getFormattedData( $tags, $context = false ) {
@@ -93,7 +93,7 @@ class FormatMetadata extends ContextSource {
 	 * formats Exif (and other metadata) values into human readable form.
 	 *
 	 * @param array $tags the Exif data to format ( as returned by
-	 *                    Exif::getFilteredData() or BitmapMetadataHandler )
+	 *   Exif::getFilteredData() or BitmapMetadataHandler )
 	 * @return array
 	 * @since 1.23
 	 */
@@ -977,14 +977,14 @@ class FormatMetadata extends ContextSource {
 	/**
 	 * Flatten an array, using the content language for any messages.
 	 *
-	 * @param array $vals array of values
+	 * @param array $vals Array of values
 	 * @param string $type Type of array (either lang, ul, ol).
-	 *     lang = language assoc array with keys being the lang code
-	 *     ul = unordered list, ol = ordered list
-	 *     type can also come from the '_type' member of $vals.
-	 * @param $noHtml Boolean If to avoid returning anything resembling
-	 *     html. (Ugly hack for backwards compatibility with old mediawiki).
-	 * @param IContextSource $context
+	 *   lang = language assoc array with keys being the lang code
+	 *   ul = unordered list, ol = ordered list
+	 *   type can also come from the '_type' member of $vals.
+	 * @param bool $noHtml If to avoid returning anything resembling HTML.
+	 *   (Ugly hack for backwards compatibility with old MediaWiki).
+	 * @param bool|IContextSource $context
 	 * @return String single value (in wiki-syntax).
 	 * @since 1.23
 	 */
@@ -1008,13 +1008,13 @@ class FormatMetadata extends ContextSource {
 	 *
 	 * @param array $vals array of values
 	 * @param string $type Type of array (either lang, ul, ol).
-	 *     lang = language assoc array with keys being the lang code
-	 *     ul = unordered list, ol = ordered list
-	 *     type can also come from the '_type' member of $vals.
-	 * @param $noHtml Boolean If to avoid returning anything resembling
-	 *     html. (Ugly hack for backwards compatibility with old mediawiki).
-	 * @param IContextSource $context
-	 * @return String single value (in wiki-syntax).
+	 *   lang = language assoc array with keys being the lang code
+	 *   ul = unordered list, ol = ordered list
+	 *   type can also come from the '_type' member of $vals.
+	 * @param bool $noHtml If to avoid returning anything resembling HTML.
+	 *   (Ugly hack for backwards compatibility with old MediaWiki).
+	 * @param bool|IContextSource $context
+	 * @return string Single value (in wiki-syntax).
 	 */
 	public static function flattenArray( $vals, $type = 'ul', $noHtml = false, $context = false ) {
 		$obj = new FormatMetadata;
@@ -1036,8 +1036,8 @@ class FormatMetadata extends ContextSource {
 	 *     lang = language assoc array with keys being the lang code
 	 *     ul = unordered list, ol = ordered list
 	 *     type can also come from the '_type' member of $vals.
-	 * @param $noHtml Boolean If to avoid returning anything resembling
-	 *     html. (Ugly hack for backwards compatibility with old mediawiki).
+	 * @param $noHtml Boolean If to avoid returning anything resembling HTML.
+	 *   (Ugly hack for backwards compatibility with old mediawiki).
 	 * @return String single value (in wiki-syntax).
 	 * @since 1.23
 	 */
@@ -1158,11 +1158,11 @@ class FormatMetadata extends ContextSource {
 	 *
 	 * @param string $value value (this is not escaped)
 	 * @param string $lang lang code of item or false
-	 * @param $default Boolean if it is default value.
-	 * @param $noHtml Boolean If to avoid html (for back-compat)
+	 * @param bool $default If it is default value.
+	 * @param bool $noHtml If to avoid html (for back-compat)
 	 * @throws MWException
-	 * @return string language item (Note: despite how this looks,
-	 * this is treated as wikitext not html).
+	 * @return string Language item (Note: despite how this looks, this is
+	 *   treated as wikitext, not as HTML).
 	 */
 	private function langItem( $value, $lang, $default = false, $noHtml = false ) {
 		if ( $lang === false && $default === false ) {
@@ -1221,12 +1221,10 @@ class FormatMetadata extends ContextSource {
 	/**
 	 * Convenience function for getFormattedData()
 	 *
-	 * @private
-	 *
-	 * @param string $tag the tag name to pass on
-	 * @param string $val the value of the tag
-	 * @param string $arg an argument to pass ($1)
-	 * @param string $arg2 a 2nd argument to pass ($2)
+	 * @param string $tag The tag name to pass on
+	 * @param string $val The value of the tag
+	 * @param string $arg An argument to pass ($1)
+	 * @param string $arg2 A 2nd argument to pass ($2)
 	 * @return string The text content of "exif-$tag-$val" message in lower case
 	 */
 	private function exifMsg( $tag, $val, $arg = null, $arg2 = null ) {
@@ -1243,8 +1241,8 @@ class FormatMetadata extends ContextSource {
 	 * Format a number, convert numbers from fractions into floating point
 	 * numbers, joins arrays of numbers with commas.
 	 *
-	 * @param $num Mixed: the value to format
-	 * @param $round float|int|bool digits to round to or false.
+	 * @param mixed $num The value to format
+	 * @param float|int|bool $round Digits to round to or false.
 	 * @return mixed A floating point number or whatever we were fed
 	 */
 	private function formatNum( $num, $round = false ) {
@@ -1280,9 +1278,7 @@ class FormatMetadata extends ContextSource {
 	/**
 	 * Format a rational number, reducing fractions
 	 *
-	 * @private
-	 *
-	 * @param $num Mixed: the value to format
+	 * @param mixed $num The value to format
 	 * @return mixed A floating point number or whatever we were fed
 	 */
 	private function formatFraction( $num ) {
@@ -1303,8 +1299,8 @@ class FormatMetadata extends ContextSource {
 	/**
 	 * Calculate the greatest common divisor of two integers.
 	 *
-	 * @param $a Integer: Numerator
-	 * @param $b Integer: Denominator
+	 * @param int $a Numerator
+	 * @param int $b Denominator
 	 * @return int
 	 * @private
 	 */
@@ -1411,8 +1407,8 @@ class FormatMetadata extends ContextSource {
 	 * Format a coordinate value, convert numbers from floating point
 	 * into degree minute second representation.
 	 *
-	 * @param int $coord degrees, minutes and seconds
-	 * @param string $type latitude or longitude (for if its a NWS or E)
+	 * @param int $coord Degrees, minutes and seconds
+	 * @param string $type Latitude or longitude (for if its a NWS or E)
 	 * @return mixed A floating point number or whatever we were fed
 	 */
 	private function formatCoords( $coord, $type ) {
@@ -1447,16 +1443,15 @@ class FormatMetadata extends ContextSource {
 	/**
 	 * Format the contact info field into a single value.
 	 *
-	 * @param array $vals array with fields of the ContactInfo
-	 *    struct defined in the IPTC4XMP spec. Or potentially
-	 *    an array with one element that is a free form text
-	 *    value from the older iptc iim 1:118 prop.
-	 *
 	 * This function might be called from
 	 * JpegHandler::convertMetadataVersion which is why it is
 	 * public.
 	 *
-	 * @return String of html-ish looking wikitext
+	 * @param array $vals Array with fields of the ContactInfo
+	 *    struct defined in the IPTC4XMP spec. Or potentially
+	 *    an array with one element that is a free form text
+	 *    value from the older iptc iim 1:118 prop.
+	 * @return string HTML-ish looking wikitext
 	 * @since 1.23 no longer static
 	 */
 	public function collapseContactInfo( $vals ) {
@@ -1888,7 +1883,7 @@ class FormatExif {
 	private $meta;
 
 	/**
-	 * @param $meta array
+	 * @param array $meta
 	 */
 	function __construct( $meta ) {
 		wfDeprecated( __METHOD__, '1.18' );
diff --git a/includes/media/GIF.php b/includes/media/GIF.php
index 830b5ca7e6..bde889c86c 100644
--- a/includes/media/GIF.php
+++ b/includes/media/GIF.php
@@ -43,7 +43,7 @@ class GIFHandler extends BitmapHandler {
 	}
 
 	/**
-	 * @param $image File
+	 * @param File $image
 	 * @return array|bool
 	 */
 	function formatMetadata( $image ) {
@@ -76,8 +76,9 @@ class GIFHandler extends BitmapHandler {
 	}
 
 	/**
-	 * @param $image File
-	 * @todo unittests
+	 * @todo Add unit tests
+	 *
+	 * @param File$image
 	 * @return bool
 	 */
 	function getImageArea( $image ) {
@@ -92,7 +93,7 @@ class GIFHandler extends BitmapHandler {
 	}
 
 	/**
-	 * @param $image File
+	 * @param File $image
 	 * @return bool
 	 */
 	function isAnimatedImage( $image ) {
@@ -151,7 +152,7 @@ class GIFHandler extends BitmapHandler {
 	}
 
 	/**
-	 * @param $image File
+	 * @param File $image
 	 * @return string
 	 */
 	function getLongDesc( $image ) {
diff --git a/includes/media/GIFMetadataExtractor.php b/includes/media/GIFMetadataExtractor.php
index 59fe15c115..178b0bf7a0 100644
--- a/includes/media/GIFMetadataExtractor.php
+++ b/includes/media/GIFMetadataExtractor.php
@@ -50,7 +50,7 @@ class GIFMetadataExtractor {
 
 	/**
 	 * @throws Exception
-	 * @param $filename string
+	 * @param string $filename
 	 * @return array
 	 */
 	static function getMetadata( $filename ) {
@@ -261,8 +261,8 @@ class GIFMetadataExtractor {
 	}
 
 	/**
-	 * @param $fh
-	 * @param $bpp
+	 * @param resource $fh
+	 * @param int $bpp
 	 * @return void
 	 */
 	static function readGCT( $fh, $bpp ) {
@@ -275,7 +275,7 @@ class GIFMetadataExtractor {
 	}
 
 	/**
-	 * @param $data
+	 * @param string $data
 	 * @throws Exception
 	 * @return int
 	 */
@@ -294,7 +294,7 @@ class GIFMetadataExtractor {
 	}
 
 	/**
-	 * @param $fh
+	 * @param resource $fh
 	 * @throws Exception
 	 */
 	static function skipBlock( $fh ) {
@@ -318,8 +318,8 @@ class GIFMetadataExtractor {
 	 * saying how long the sub-block is, followed by the sub-block.
 	 * The entire block is terminated by a sub-block of length
 	 * 0.
-	 * @param $fh FileHandle
-	 * @param $includeLengths Boolean Include the length bytes of the
+	 * @param resource $fh File handle
+	 * @param bool $includeLengths Include the length bytes of the
 	 *  sub-blocks in the returned value. Normally this is false,
 	 *  except XMP is weird and does a hack where you need to keep
 	 *  these length bytes.
diff --git a/includes/media/IPTC.php b/includes/media/IPTC.php
index ee0233ecfa..503b968642 100644
--- a/includes/media/IPTC.php
+++ b/includes/media/IPTC.php
@@ -35,7 +35,7 @@ class IPTC {
 	 * @see http://www.iptc.org/std/IIM/4.1/specification/IIMV4.1.pdf
 	 *
 	 * @param string $rawData app13 block from jpeg containing iptc/iim data
-	 * @return Array iptc metadata array
+	 * @return array IPTC metadata array
 	 */
 	static function parse( $rawData ) {
 		$parsed = iptcparse( $rawData );
@@ -353,8 +353,8 @@ class IPTC {
 	 * @todo Potentially this should also capture the timezone offset.
 	 * @param array $date The date tag
 	 * @param array $time The time tag
-	 * @param $c
-	 * @return String Date in exif format.
+	 * @param string $c The charset
+	 * @return string Date in EXIF format.
 	 */
 	private static function timeHelper( $date, $time, $c ) {
 		if ( count( $date ) === 1 ) {
@@ -438,7 +438,7 @@ class IPTC {
 
 	/**
 	 * Helper function of a helper function to convert charset for iptc values.
-	 * @param $data Mixed String or Array: The iptc string
+	 * @param string|array $data The IPTC string
 	 * @param string $charset The charset
 	 *
 	 * @return string
diff --git a/includes/media/ImageHandler.php b/includes/media/ImageHandler.php
index eecef1d591..4dd79a80e7 100644
--- a/includes/media/ImageHandler.php
+++ b/includes/media/ImageHandler.php
@@ -28,7 +28,7 @@
  */
 abstract class ImageHandler extends MediaHandler {
 	/**
-	 * @param $file File
+	 * @param File $file
 	 * @return bool
 	 */
 	function canRender( $file ) {
@@ -79,8 +79,8 @@ abstract class ImageHandler extends MediaHandler {
 	}
 
 	/**
-	 * @param $image File
-	 * @param  $params
+	 * @param File $image
+	 * @param array $params
 	 * @return bool
 	 */
 	function normaliseParams( $image, &$params ) {
@@ -151,11 +151,11 @@ abstract class ImageHandler extends MediaHandler {
 	/**
 	 * Validate thumbnail parameters and fill in the correct height
 	 *
-	 * @param $width Integer: specified width (input/output)
-	 * @param $height Integer: height (output only)
-	 * @param $srcWidth Integer: width of the source image
-	 * @param $srcHeight Integer: height of the source image
-	 * @param $mimeType
+	 * @param int $width Specified width (input/output)
+	 * @param int $height Height (output only)
+	 * @param int $srcWidth Width of the source image
+	 * @param int $srcHeight Height of the source image
+	 * @param string $mimeType Unused
 	 * @return bool False to indicate that an error should be returned to the user.
 	 */
 	function validateThumbParams( &$width, &$height, $srcWidth, $srcHeight, $mimeType ) {
@@ -183,10 +183,10 @@ abstract class ImageHandler extends MediaHandler {
 	}
 
 	/**
-	 * @param $image File
-	 * @param  $script
-	 * @param  $params
-	 * @return bool|ThumbnailImage
+	 * @param File $image
+	 * @param string $script
+	 * @param array $params
+	 * @return bool|MediaTransformOutput
 	 */
 	function getScriptedTransform( $image, $script, $params ) {
 		if ( !$this->normaliseParams( $image, $params ) ) {
@@ -221,7 +221,7 @@ abstract class ImageHandler extends MediaHandler {
 	}
 
 	/**
-	 * @param $file File
+	 * @param File $file
 	 * @return string
 	 */
 	function getShortDesc( $file ) {
@@ -234,7 +234,7 @@ abstract class ImageHandler extends MediaHandler {
 	}
 
 	/**
-	 * @param $file File
+	 * @param File $file
 	 * @return string
 	 */
 	function getLongDesc( $file ) {
@@ -255,7 +255,7 @@ abstract class ImageHandler extends MediaHandler {
 	}
 
 	/**
-	 * @param $file File
+	 * @param File $file
 	 * @return string
 	 */
 	function getDimensionsString( $file ) {
diff --git a/includes/media/Jpeg.php b/includes/media/Jpeg.php
index 213bee09db..ee7eff86ec 100644
--- a/includes/media/Jpeg.php
+++ b/includes/media/Jpeg.php
@@ -61,7 +61,7 @@ class JpegHandler extends ExifBitmapHandler {
 	}
 
 	/**
-	 * @param $file File
+	 * @param File $file
 	 * @param array $params Rotate parameters.
 	 *    'rotation' clockwise rotation in degrees, allowed are multiples of 90
 	 * @since 1.21
@@ -80,6 +80,7 @@ class JpegHandler extends ExifBitmapHandler {
 			wfDebug( __METHOD__ . ": running jpgtran: $cmd\n" );
 			wfProfileIn( 'jpegtran' );
 			$retval = 0;
+			// @todo FIXME Undefined variable $env
 			$err = wfShellExecWithStderr( $cmd, $retval, $env );
 			wfProfileOut( 'jpegtran' );
 			if ( $retval !== 0 ) {
diff --git a/includes/media/JpegMetadataExtractor.php b/includes/media/JpegMetadataExtractor.php
index 00be258933..a0f85247a5 100644
--- a/includes/media/JpegMetadataExtractor.php
+++ b/includes/media/JpegMetadataExtractor.php
@@ -44,7 +44,7 @@ class JpegMetadataExtractor {
 	 * and those can't extract xmp on files containing both exif and xmp data
 	 *
 	 * @param string $filename name of jpeg file
-	 * @return Array of interesting segments.
+	 * @return array of interesting segments.
 	 * @throws MWException if given invalid file.
 	 */
 	static function segmentSplitter( $filename ) {
@@ -167,9 +167,9 @@ class JpegMetadataExtractor {
 
 	/**
 	 * Helper function for jpegSegmentSplitter
-	 * @param &$fh FileHandle for jpeg file
+	 * @param resource &$fh File handle for JPEG file
 	 * @throws MWException
-	 * @return string data content of segment.
+	 * @return string Data content of segment.
 	 */
 	private static function jpegExtractMarker( &$fh ) {
 		$size = wfUnpack( "nint", fread( $fh, 2 ), 2 );
@@ -195,7 +195,8 @@ class JpegMetadataExtractor {
 	 *
 	 * @param string $app13 photoshop psir app13 block from jpg.
 	 * @throws MWException (It gets caught next level up though)
-	 * @return String if the iptc hash is good or not.
+	 * @return string If the iptc hash is good or not. One of 'iptc-no-hash',
+	 *   'iptc-good-hash', 'iptc-bad-hash'.
 	 */
 	public static function doPSIR( $app13 ) {
 		if ( !$app13 ) {
diff --git a/includes/media/MediaHandler.php b/includes/media/MediaHandler.php
index b002dfb0a0..b3be21eef7 100644
--- a/includes/media/MediaHandler.php
+++ b/includes/media/MediaHandler.php
@@ -43,7 +43,6 @@ abstract class MediaHandler {
 	 * Get a MediaHandler for a given MIME type from the instance cache
 	 *
 	 * @param string $type
-	 *
 	 * @return MediaHandler
 	 */
 	static function getHandler( $type ) {
@@ -76,7 +75,7 @@ abstract class MediaHandler {
 	 * If you return false, the parser will do something quiet and forgiving.
 	 *
 	 * @param string $name
-	 * @param $value
+	 * @param mixed $value
 	 */
 	abstract function validateParam( $name, $value );
 
@@ -100,8 +99,8 @@ abstract class MediaHandler {
 	 * Changes the parameter array as necessary, ready for transformation.
 	 * Should be idempotent.
 	 * Returns false if the parameters are unacceptable and the transform should fail
-	 * @param $image
-	 * @param $params
+	 * @param File $image
+	 * @param array $params
 	 */
 	abstract function normaliseParams( $image, &$params );
 
@@ -111,7 +110,8 @@ abstract class MediaHandler {
 	 *
 	 * @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
+	 * @return array Follow the format of PHP getimagesize() internal function.
+	 *   See http://www.php.net/getimagesize
 	 */
 	abstract function getImageSize( $image, $path );
 
@@ -155,7 +155,7 @@ abstract class MediaHandler {
 	 * By default just returns $metadata, but can be used to allow
 	 * media handlers to convert between metadata versions.
 	 *
-	 * @param mixed|string|array $metadata Metadata array (serialized if string)
+	 * @param string|array $metadata Metadata array (serialized if string)
 	 * @param int $version Target version
 	 * @return array Serialized metadata in specified version, or $metadata on fail.
 	 */
@@ -175,7 +175,7 @@ abstract class MediaHandler {
 
 	/**
 	 * Get a string describing the type of metadata, for display purposes.
-	 * @param $image
+	 * @param File $image
 	 * @return string
 	 */
 	function getMetadataType( $image ) {
@@ -189,6 +189,8 @@ abstract class MediaHandler {
 	 * MediaHandler::METADATA_GOOD for if the metadata is a-ok,
 	 * MediaHanlder::METADATA_COMPATIBLE if metadata is old but backwards
 	 * compatible (which may or may not trigger a metadata reload).
+	 * @param File $image
+	 * @param array $metadata
 	 * @return bool
 	 */
 	function isMetadataValid( $image, $metadata ) {
@@ -224,7 +226,6 @@ abstract class MediaHandler {
 	 * this interface, it should return an empty array, not false.
 	 *
 	 * @param File $file
-	 *
 	 * @return array|bool False if interface not supported
 	 * @since 1.23
 	 */
@@ -239,7 +240,10 @@ abstract class MediaHandler {
 	 * Used when the repository has a thumbnailScriptUrl option configured.
 	 *
 	 * Return false to fall back to the regular getTransform().
-	 * @return bool
+	 * @param File $image
+	 * @param string $script
+	 * @param array $params
+	 * @return bool|ThumbnailImage
 	 */
 	function getScriptedTransform( $image, $script, $params ) {
 		return false;
@@ -250,7 +254,7 @@ abstract class MediaHandler {
 	 * actually do the transform.
 	 *
 	 * @param File $image The image object
-	 * @param string $dstPath filesystem destination path
+	 * @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()
 	 * @return MediaTransformOutput
@@ -264,12 +268,11 @@ abstract class MediaHandler {
 	 * transform unless $flags contains self::TRANSFORM_LATER.
 	 *
 	 * @param File $image The image object
-	 * @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()
+	 * @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 int $flags A bitfield, may contain self::TRANSFORM_LATER
-	 *
 	 * @return MediaTransformOutput
 	 */
 	abstract function doTransform( $image, $dstPath, $dstUrl, $params, $flags = 0 );
@@ -278,7 +281,7 @@ 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 string $mime MIME type of original file
 	 * @param array $params Handler specific rendering parameters
 	 * @return array thumbnail extension and MIME type
 	 */
@@ -300,6 +303,7 @@ abstract class MediaHandler {
 
 	/**
 	 * Get useful response headers for GET/HEAD requests for a file with the given metadata
+	 *
 	 * @param mixed $metadata Result of the getMetadata() function of this handler for a file
 	 * @return array
 	 */
@@ -309,6 +313,8 @@ abstract class MediaHandler {
 
 	/**
 	 * True if the handled types can be transformed
+	 *
+	 * @param File $file
 	 * @return bool
 	 */
 	function canRender( $file ) {
@@ -318,6 +324,8 @@ abstract class MediaHandler {
 	/**
 	 * True if handled types cannot be displayed directly in a browser
 	 * but can be rendered
+	 *
+	 * @param File $file
 	 * @return bool
 	 */
 	function mustRender( $file ) {
@@ -326,6 +334,8 @@ abstract class MediaHandler {
 
 	/**
 	 * True if the type has multi-page capabilities
+	 *
+	 * @param File $file
 	 * @return bool
 	 */
 	function isMultiPage( $file ) {
@@ -334,6 +344,8 @@ abstract class MediaHandler {
 
 	/**
 	 * Page count for a multi-page document, false if unsupported or unknown
+	 *
+	 * @param File $file
 	 * @return bool
 	 */
 	function pageCount( $file ) {
@@ -342,6 +354,8 @@ abstract class MediaHandler {
 
 	/**
 	 * The material is vectorized and thus scaling is lossless
+	 *
+	 * @param File $file
 	 * @return bool
 	 */
 	function isVectorized( $file ) {
@@ -352,6 +366,8 @@ abstract class MediaHandler {
 	 * The material is an image, and is animated.
 	 * In particular, video material need not return true.
 	 * @note Before 1.20, this was a method of ImageHandler only
+	 *
+	 * @param File $file
 	 * @return bool
 	 */
 	function isAnimatedImage( $file ) {
@@ -361,6 +377,8 @@ abstract class MediaHandler {
 	/**
 	 * If the material is animated, we can animate the thumbnail
 	 * @since 1.20
+	 *
+	 * @param File $file
 	 * @return bool If material is not animated, handler may return any value.
 	 */
 	function canAnimateThumbnail( $file ) {
@@ -406,7 +424,9 @@ abstract class MediaHandler {
 	/**
 	 * Generic getter for text layer.
 	 * Currently overloaded by PDF and DjVu handlers
-	 * @return bool
+	 * @param File $image
+	 * @param int $page Page number to get information for
+	 * @return bool|string Page text or false when no text found.
 	 */
 	function getPageText( $image, $page ) {
 		return false;
@@ -432,12 +452,12 @@ abstract class MediaHandler {
 	 */
 
 	/**
-	 * @todo FIXME: I don't really like this interface, it's not very flexible
-	 * I think the media handler should generate HTML instead. It can do
-	 * all the formatting according to some standard. That makes it possible
-	 * to do things like visual indication of grouped and chained streams
-	 * in ogg container files.
-	 * @return bool
+	 * @todo FIXME: This interface is not very flexible. The media handler
+	 * should generate HTML instead. It can do all the formatting according
+	 * to some standard. That makes it possible to do things like visual
+	 * indication of grouped and chained streams in ogg container files.
+	 * @param File $image
+	 * @return array|bool
 	 */
 	function formatMetadata( $image ) {
 		return false;
@@ -449,7 +469,7 @@ abstract class MediaHandler {
 	 *
 	 * This is used by the media handlers that use the FormatMetadata class
 	 *
-	 * @param array $metadataArray metadata array
+	 * @param array $metadataArray Metadata array
 	 * @return array for use displaying metadata.
 	 */
 	function formatMetadataHelper( $metadataArray ) {
@@ -479,7 +499,6 @@ abstract class MediaHandler {
 	 * the metadata table is collapsed.
 	 *
 	 * @return array of strings
-	 * @access protected
 	 */
 	function visibleMetadataFields() {
 		return FormatMetadata::getVisibleFields();
@@ -490,21 +509,21 @@ abstract class MediaHandler {
 	 * That array is then used to generate the table of metadata values
 	 * on the image page
 	 *
-	 * @param &$array Array An array containing elements for each type of visibility
-	 * and each of those elements being an array of metadata items. This function adds
-	 * a value to that array.
+	 * @param array &$array An array containing elements for each type of visibility
+	 *   and each of those elements being an array of metadata items. This function adds
+	 *   a value to that array.
 	 * @param string $visibility ('visible' or 'collapsed') if this value is hidden
-	 * by default.
-	 * @param string $type type of metadata tag (currently always 'exif')
-	 * @param string $id the name of the metadata tag (like 'artist' for example).
-	 * its name in the table displayed is the message "$type-$id" (Ex exif-artist ).
-	 * @param string $value thingy goes into a wikitext table; it used to be escaped but
-	 * that was incompatible with previous practise of customized display
-	 * with wikitext formatting via messages such as 'exif-model-value'.
-	 * So the escaping is taken back out, but generally this seems a confusing
-	 * interface.
-	 * @param string $param value to pass to the message for the name of the field
-	 * as $1. Currently this parameter doesn't seem to ever be used.
+	 *   by default.
+	 * @param string $type Type of metadata tag (currently always 'exif')
+	 * @param string $id The name of the metadata tag (like 'artist' for example).
+	 *   its name in the table displayed is the message "$type-$id" (Ex exif-artist ).
+	 * @param string $value Thingy goes into a wikitext table; it used to be escaped but
+	 *   that was incompatible with previous practise of customized display
+	 *   with wikitext formatting via messages such as 'exif-model-value'.
+	 *   So the escaping is taken back out, but generally this seems a confusing
+	 *   interface.
+	 * @param bool|string $param Value to pass to the message for the name of the field
+	 *   as $1. Currently this parameter doesn't seem to ever be used.
 	 *
 	 * Note, everything here is passed through the parser later on (!)
 	 */
@@ -531,7 +550,7 @@ abstract class MediaHandler {
 	/**
 	 * Used instead of getLongDesc if there is no handler registered for file.
 	 *
-	 * @param $file File
+	 * @param File $file
 	 * @return string
 	 */
 	function getShortDesc( $file ) {
@@ -543,7 +562,7 @@ abstract class MediaHandler {
 	/**
 	 * Short description. Shown on Special:Search results.
 	 *
-	 * @param $file File
+	 * @param File $file
 	 * @return string
 	 */
 	function getLongDesc( $file ) {
@@ -556,7 +575,7 @@ abstract class MediaHandler {
 	/**
 	 * Long description. Shown under image on image description page surounded by ().
 	 *
-	 * @param $file File
+	 * @param File $file
 	 * @return string
 	 */
 	static function getGeneralShortDesc( $file ) {
@@ -568,7 +587,7 @@ abstract class MediaHandler {
 	/**
 	 * Used instead of getShortDesc if there is no handler registered for file.
 	 *
-	 * @param $file File
+	 * @param File $file
 	 * @return string
 	 */
 	static function getGeneralLongDesc( $file ) {
@@ -581,10 +600,10 @@ abstract class MediaHandler {
 	/**
 	 * Calculate the largest thumbnail width for a given original file size
 	 * such that the thumbnail's height is at most $maxHeight.
-	 * @param $boxWidth Integer Width of the thumbnail box.
-	 * @param $boxHeight Integer Height of the thumbnail box.
-	 * @param $maxHeight Integer Maximum height expected for the thumbnail.
-	 * @return Integer.
+	 * @param int $boxWidth Width of the thumbnail box.
+	 * @param int $boxHeight Height of the thumbnail box.
+	 * @param int $maxHeight Maximum height expected for the thumbnail.
+	 * @return int
 	 */
 	public static function fitBoxWidth( $boxWidth, $boxHeight, $maxHeight ) {
 		$idealWidth = $boxWidth * $maxHeight / $boxHeight;
@@ -701,7 +720,7 @@ abstract class MediaHandler {
 	 *
 	 * For files we don't know, we return 0.
 	 *
-	 * @param $file File
+	 * @param File $file
 	 * @return int 0, 90, 180 or 270
 	 */
 	public function getRotation( $file ) {
@@ -714,10 +733,10 @@ abstract class MediaHandler {
 	 * Moved from BitmapHandler to MediaHandler with MediaWiki 1.23
 	 *
 	 * @since 1.23
-	 * @param $retval int
-	 * @param $err string Error reported by command. Anything longer than
+	 * @param int $retval
+	 * @param string $err Error reported by command. Anything longer than
 	 * MediaHandler::MAX_ERR_LOG_SIZE is stripped off.
-	 * @param $cmd string
+	 * @param string $cmd
 	 */
 	protected function logErrorForExternalProcess( $retval, $err, $cmd ) {
 		# Keep error output limited (bug 57985)
diff --git a/includes/media/MediaTransformOutput.php b/includes/media/MediaTransformOutput.php
index cfb163cb4b..41b09e6b48 100644
--- a/includes/media/MediaTransformOutput.php
+++ b/includes/media/MediaTransformOutput.php
@@ -27,9 +27,8 @@
  * @ingroup Media
  */
 abstract class MediaTransformOutput {
-	/**
-	 * @var array Associative array mapping optional supplementary image files
-	 * from pixel density (eg 1.5 or 2) to additional URLs.
+	/** @var array Associative array mapping optional supplementary image files
+	 *  from pixel density (eg 1.5 or 2) to additional URLs.
 	 */
 	public $responsiveUrls = array();
 
@@ -58,14 +57,14 @@ abstract class MediaTransformOutput {
 	protected $storagePath = false;
 
 	/**
-	 * @return integer Width of the output box
+	 * @return int Width of the output box
 	 */
 	public function getWidth() {
 		return $this->width;
 	}
 
 	/**
-	 * @return integer Height of the output box
+	 * @return int Height of the output box
 	 */
 	public function getHeight() {
 		return $this->height;
@@ -138,7 +137,7 @@ abstract class MediaTransformOutput {
 	 * thumbnail is to be handled client-side only, or if
 	 * transformation was deferred via TRANSFORM_LATER.
 	 *
-	 * @return Bool
+	 * @return bool
 	 */
 	public function hasFile() {
 		// If TRANSFORM_LATER, $this->path will be false.
@@ -150,7 +149,7 @@ abstract class MediaTransformOutput {
 	 * Check if the output thumbnail is the same as the source.
 	 * This can occur if the requested width was bigger than the source.
 	 *
-	 * @return Bool
+	 * @return bool
 	 */
 	public function fileIsSource() {
 		return ( !$this->isError() && $this->path === null );
@@ -182,7 +181,7 @@ abstract class MediaTransformOutput {
 	 * Stream the file if there were no errors
 	 *
 	 * @param array $headers Additional HTTP headers to send on success
-	 * @return Bool success
+	 * @return bool Success
 	 */
 	public function streamFile( $headers = array() ) {
 		if ( !$this->path ) {
@@ -199,9 +198,8 @@ abstract class MediaTransformOutput {
 	/**
 	 * Wrap some XHTML text in an anchor tag with the given attributes
 	 *
-	 * @param $linkAttribs array
-	 * @param $contents string
-	 *
+	 * @param array $linkAttribs
+	 * @param string $contents
 	 * @return string
 	 */
 	protected function linkWrap( $linkAttribs, $contents ) {
@@ -214,7 +212,7 @@ abstract class MediaTransformOutput {
 
 	/**
 	 * @param $title string
-	 * @param $params string|array Query parameters to add
+	 * @param string|array $params Query parameters to add
 	 * @return array
 	 */
 	public function getDescLinkAttribs( $title = null, $params = array() ) {
@@ -259,11 +257,10 @@ class ThumbnailImage extends MediaTransformOutput {
 	 * $parameters should include, as a minimum, (file) 'width' and 'height'.
 	 * It may also include a 'page' parameter for multipage files.
 	 *
-	 * @param $file File object
+	 * @param File $file
 	 * @param string $url URL path to the thumb
-	 * @param $path String|bool|null: filesystem path to the thumb
+	 * @param string|bool $path Filesystem path to the thumb
 	 * @param array $parameters Associative array of parameters
-	 * @private
 	 */
 	function __construct( $file, $url, $path = false, $parameters = array() ) {
 		# Previous parameters:
@@ -356,6 +353,7 @@ class ThumbnailImage extends MediaTransformOutput {
 				$linkAttribs['rel'] = $options['parser-extlink-rel'];
 			}
 		} elseif ( !empty( $options['custom-title-link'] ) ) {
+			/** @var Title $title */
 			$title = $options['custom-title-link'];
 			$linkAttribs = array(
 				'href' => $title->getLinkURL(),
diff --git a/includes/media/PNG.php b/includes/media/PNG.php
index fd26575c1e..968db10aa8 100644
--- a/includes/media/PNG.php
+++ b/includes/media/PNG.php
@@ -48,7 +48,7 @@ class PNGHandler extends BitmapHandler {
 	}
 
 	/**
-	 * @param $image File
+	 * @param File $image
 	 * @return array|bool
 	 */
 	function formatMetadata( $image ) {
@@ -63,7 +63,7 @@ class PNGHandler extends BitmapHandler {
 	/**
 	 * Get a file type independent array of metadata.
 	 *
-	 * @param $image File
+	 * @param File $image
 	 * @return array The metadata array
 	 */
 	public function getCommonMetaArray( File $image ) {
@@ -82,7 +82,7 @@ class PNGHandler extends BitmapHandler {
 	}
 
 	/**
-	 * @param $image File
+	 * @param File $image
 	 * @return bool
 	 */
 	function isAnimatedImage( $image ) {
@@ -99,7 +99,7 @@ class PNGHandler extends BitmapHandler {
 
 	/**
 	 * We do not support making APNG thumbnails, so always false
-	 * @param $image File
+	 * @param File $image
 	 * @return bool false
 	 */
 	function canAnimateThumbnail( $image ) {
@@ -139,7 +139,7 @@ class PNGHandler extends BitmapHandler {
 	}
 
 	/**
-	 * @param $image File
+	 * @param File $image
 	 * @return string
 	 */
 	function getLongDesc( $image ) {
diff --git a/includes/media/PNGMetadataExtractor.php b/includes/media/PNGMetadataExtractor.php
index b9377be0af..30376f1e1b 100644
--- a/includes/media/PNGMetadataExtractor.php
+++ b/includes/media/PNGMetadataExtractor.php
@@ -411,10 +411,10 @@ class PNGMetadataExtractor {
 	/**
 	 * Read a chunk, checking to make sure its not too big.
 	 *
-	 * @param $fh resource The file handle
-	 * @param $size Integer size in bytes.
+	 * @param resource $fh The file handle
+	 * @param int $size Size in bytes.
 	 * @throws Exception if too big.
-	 * @return String The chunk.
+	 * @return string The chunk.
 	 */
 	private static function read( $fh, $size ) {
 		if ( $size > self::MAX_CHUNK_SIZE ) {
diff --git a/includes/media/SVG.php b/includes/media/SVG.php
index fef67f8df7..6864de4675 100644
--- a/includes/media/SVG.php
+++ b/includes/media/SVG.php
@@ -29,10 +29,9 @@
 class SvgHandler extends ImageHandler {
 	const SVG_METADATA_VERSION = 2;
 
-	/**
-	 * A list of metadata tags that can be converted
-	 * to the commonly used exif tags. This allows messages
-	 * to be reused, and consistent tag names for {{#formatmetadata:..}}
+	/** @var array A list of metadata tags that can be converted
+	 *  to the commonly used exif tags. This allows messages
+	 *  to be reused, and consistent tag names for {{#formatmetadata:..}}
 	 */
 	private static $metaConversion = array(
 		'originalwidth' => 'ImageWidth',
@@ -61,11 +60,11 @@ class SvgHandler extends ImageHandler {
 	}
 
 	/**
-	 * @param $file File
+	 * @param File $file
 	 * @return bool
 	 */
 	function isAnimatedImage( $file ) {
-		# TODO: detect animated SVGs
+		# @todo Detect animated SVGs
 		$metadata = $file->getMetadata();
 		if ( $metadata ) {
 			$metadata = $this->unpackMetadata( $metadata );
@@ -85,8 +84,8 @@ class SvgHandler extends ImageHandler {
 	}
 
 	/**
-	 * @param $image File
-	 * @param  $params
+	 * @param File $image
+	 * @param array $params
 	 * @return bool
 	 */
 	function normaliseParams( $image, &$params ) {
@@ -115,10 +114,10 @@ class SvgHandler extends ImageHandler {
 	}
 
 	/**
-	 * @param $image File
-	 * @param  $dstPath
-	 * @param  $dstUrl
-	 * @param  $params
+	 * @param File $image
+	 * @param string $dstPath
+	 * @param string $dstUrl
+	 * @param array $params
 	 * @param int $flags
 	 * @return bool|MediaTransformError|ThumbnailImage|TransformParameterError
 	 */
@@ -164,7 +163,7 @@ class SvgHandler extends ImageHandler {
 	 * @param string $dstPath
 	 * @param string $width
 	 * @param string $height
-	 * @param string $lang Language code of the language to render the SVG in
+	 * @param bool|string $lang Language code of the language to render the SVG in
 	 * @throws MWException
 	 * @return bool|MediaTransformError
 	 */
@@ -230,9 +229,9 @@ class SvgHandler extends ImageHandler {
 	}
 
 	/**
-	 * @param $file File
-	 * @param  $path
-	 * @param bool $metadata
+	 * @param File $file
+	 * @param string $path Unused
+	 * @param bool|array $metadata
 	 * @return array
 	 */
 	function getImageSize( $file, $path, $metadata = false ) {
@@ -259,7 +258,7 @@ class SvgHandler extends ImageHandler {
 	 * a "nominal" resolution, and not a fixed one,
 	 * as well as so animation can be denoted.
 	 *
-	 * @param $file File
+	 * @param File $file
 	 * @return string
 	 */
 	function getLongDesc( $file ) {
@@ -283,6 +282,11 @@ class SvgHandler extends ImageHandler {
 		return $msg->parse();
 	}
 
+	/**
+	 * @param File $file
+	 * @param string $filename
+	 * @return string Serialised metadata
+	 */
 	function getMetadata( $file, $filename ) {
 		$metadata = array( 'version' => self::SVG_METADATA_VERSION );
 		try {
@@ -334,7 +338,7 @@ class SvgHandler extends ImageHandler {
 	}
 
 	/**
-	 * @param $file File
+	 * @param File $file
 	 * @return array|bool
 	 */
 	function formatMetadata( $file ) {
@@ -351,7 +355,7 @@ class SvgHandler extends ImageHandler {
 			return false;
 		}
 
-		/* TODO: add a formatter
+		/* @todo Add a formatter
 		$format = new FormatSVG( $metadata );
 		$formatted = $format->getFormattedData();
 		*/
@@ -382,7 +386,7 @@ class SvgHandler extends ImageHandler {
 
 	/**
 	 * @param string $name Parameter name
-	 * @param $string $value Parameter value
+	 * @param mixed $value Parameter value
 	 * @return bool Validity
 	 */
 	function validateParam( $name, $value ) {
@@ -437,7 +441,7 @@ class SvgHandler extends ImageHandler {
 	}
 
 	/**
-	 * @param $params
+	 * @param array $params
 	 * @return array
 	 */
 	function getScriptParams( $params ) {
diff --git a/includes/media/SVGMetadataExtractor.php b/includes/media/SVGMetadataExtractor.php
index d332c3f3c1..db58c6200c 100644
--- a/includes/media/SVGMetadataExtractor.php
+++ b/includes/media/SVGMetadataExtractor.php
@@ -44,10 +44,13 @@ class SVGReader {
 	const DEFAULT_HEIGHT = 512;
 	const NS_SVG = 'http://www.w3.org/2000/svg';
 
+	/** @var null|XMLReader */
 	private $reader = null;
 
+	/** @var bool */
 	private $mDebug = false;
 
+	/** @var array */
 	private $metadata = array();
 
 	/**
@@ -187,8 +190,8 @@ class SVGReader {
 	/**
 	 * Read a textelement from an element
 	 *
-	 * @param string $name of the element that we are reading from
-	 * @param string $metafield that we will fill with the result
+	 * @param string $name Name of the element that we are reading from
+	 * @param string $metafield Field that we will fill with the result
 	 */
 	private function readField( $name, $metafield = null ) {
 		$this->debug( "Read field $metafield" );
@@ -212,7 +215,7 @@ class SVGReader {
 	/**
 	 * Read an XML snippet from an element
 	 *
-	 * @param string $metafield that we will fill with the result
+	 * @param string $metafield Field that we will fill with the result
 	 * @throws MWException
 	 */
 	private function readXml( $metafield = null ) {
@@ -220,7 +223,7 @@ class SVGReader {
 		if ( !$metafield || $this->reader->nodeType != XmlReader::ELEMENT ) {
 			return;
 		}
-		// TODO: find and store type of xml snippet. metadata['metadataType'] = "rdf"
+		// @todo Find and store type of xml snippet. metadata['metadataType'] = "rdf"
 		if ( method_exists( $this->reader, 'readInnerXML' ) ) {
 			$this->metadata[$metafield] = trim( $this->reader->readInnerXML() );
 		} else {
@@ -234,7 +237,7 @@ class SVGReader {
 	/**
 	 * Filter all children, looking for animate elements
 	 *
-	 * @param string $name of the element that we are reading from
+	 * @param string $name Name of the element that we are reading from
 	 */
 	private function animateFilter( $name ) {
 		$this->debug( "animate filter for tag $name" );
@@ -274,6 +277,7 @@ class SVGReader {
 		}
 	}
 
+	// @todo FIXME: Unused, remove?
 	private function throwXmlError( $err ) {
 		$this->debug( "FAILURE: $err" );
 		wfDebug( "SVGReader XML error: $err\n" );
@@ -285,10 +289,12 @@ class SVGReader {
 		}
 	}
 
+	// @todo FIXME: Unused, remove?
 	private function warn( $data ) {
 		wfDebug( "SVGReader: $data\n" );
 	}
 
+	// @todo FIXME: Unused, remove?
 	private function notice( $data ) {
 		wfDebug( "SVGReader WARN: $data\n" );
 	}
@@ -346,8 +352,8 @@ class SVGReader {
 	 * http://www.w3.org/TR/SVG11/coords.html#UnitIdentifiers
 	 *
 	 * @param string $length CSS/SVG length.
-	 * @param $viewportSize : Float optional scale for percentage units...
-	 * @return float: length in pixels
+	 * @param float|int $viewportSize Optional scale for percentage units...
+	 * @return float Length in pixels
 	 */
 	static function scaleSVGUnit( $length, $viewportSize = 512 ) {
 		static $unitLength = array(
diff --git a/includes/media/Tiff.php b/includes/media/Tiff.php
index dda8265bf8..6964170198 100644
--- a/includes/media/Tiff.php
+++ b/includes/media/Tiff.php
@@ -35,8 +35,7 @@ class TiffHandler extends ExifBitmapHandler {
 	 * InstantCommons will have thumbnails managed from the remote instance,
 	 * so we can skip this check.
 	 *
-	 * @param $file
-	 *
+	 * @param File $file
 	 * @return bool
 	 */
 	function canRender( $file ) {
@@ -50,8 +49,7 @@ class TiffHandler extends ExifBitmapHandler {
 	 * Browsers don't support TIFF inline generally...
 	 * For inline display, we need to convert to PNG.
 	 *
-	 * @param $file
-	 *
+	 * @param File $file
 	 * @return bool
 	 */
 	function mustRender( $file ) {
@@ -59,9 +57,9 @@ class TiffHandler extends ExifBitmapHandler {
 	}
 
 	/**
-	 * @param $ext
-	 * @param $mime
-	 * @param $params
+	 * @param string $ext
+	 * @param string $mime
+	 * @param array $params
 	 * @return bool
 	 */
 	function getThumbType( $ext, $mime, $params = null ) {
diff --git a/includes/media/XCF.php b/includes/media/XCF.php
index 9f11ca76b6..41e6f036c0 100644
--- a/includes/media/XCF.php
+++ b/includes/media/XCF.php
@@ -34,7 +34,7 @@
  */
 class XCFHandler extends BitmapHandler {
 	/**
-	 * @param $file
+	 * @param File $file
 	 * @return bool
 	 */
 	function mustRender( $file ) {
@@ -44,9 +44,9 @@ class XCFHandler extends BitmapHandler {
 	/**
 	 * Render files as PNG
 	 *
-	 * @param $ext
-	 * @param $mime
-	 * @param $params
+	 * @param string $ext
+	 * @param string $mime
+	 * @param array $params
 	 * @return array
 	 */
 	function getThumbType( $ext, $mime, $params = null ) {
@@ -56,8 +56,8 @@ class XCFHandler extends BitmapHandler {
 	/**
 	 * Get width and height from the XCF header.
 	 *
-	 * @param $image
-	 * @param $filename
+	 * @param File $image
+	 * @param string $filename
 	 * @return array
 	 */
 	function getImageSize( $image, $filename ) {
@@ -146,6 +146,8 @@ class XCFHandler extends BitmapHandler {
 	/**
 	 * Must use "im" for XCF
 	 *
+	 * @param string $dstPath
+	 * @param bool $checkDstPath
 	 * @return string
 	 */
 	protected static function getScalerType( $dstPath, $checkDstPath = true ) {
diff --git a/includes/media/XMP.php b/includes/media/XMP.php
index 795299cf5f..08d416a620 100644
--- a/includes/media/XMP.php
+++ b/includes/media/XMP.php
@@ -47,28 +47,39 @@
  *
  */
 class XMPReader {
-	private $curItem = array(); // array to hold the current element (and previous element, and so on)
+	/** @var array XMP item configuration array */
+	protected $items;
+
+	/** @var array Array to hold the current element (and previous element, and so on) */
+	private $curItem = array();
 
-	private $ancestorStruct = false; // the structure name when processing nested structures.
+	/** @var bool|string The structure name when processing nested structures. */
+	private $ancestorStruct = false;
 
-	private $charContent = false; // temporary holder for character data that appears in xmp doc.
+	/** @var bool|string Temporary holder for character data that appears in xmp doc. */
+	private $charContent = false;
 
-	private $mode = array(); // stores the state the xmpreader is in (see MODE_FOO constants)
+	/** @var array Stores the state the xmpreader is in (see MODE_FOO constants) */
+	private $mode = array();
 
-	private $results = array(); // array to hold results
+	/** @var array Array to hold results */
+	private $results = array();
 
-	private $processingArray = false; // if we're doing a seq or bag.
+	/** @var bool If we're doing a seq or bag. */
+	private $processingArray = false;
 
-	private $itemLang = false; // used for lang alts only
+	/** @var bool|string Used for lang alts only */
+	private $itemLang = false;
 
+	/** @var resource A resource handle for the XML parser */
 	private $xmlParser;
 
+	/** @var bool|string Character set like 'UTF-8' */
 	private $charset = false;
 
+	/** @var int */
 	private $extendedXMPOffset = 0;
 
-	protected $items;
-
 	/**
 	 * These are various mode constants.
 	 * they are used to figure out what to do
@@ -244,10 +255,10 @@ class XMPReader {
 	 * debug log, blanks result array and returns false.
 	 *
 	 * @param string $content XMP data
-	 * @param $allOfIt Boolean: If this is all the data (true) or if its split up (false). Default true
-	 * @param $reset Boolean: does xml parser need to be reset. Default false
+	 * @param bool $allOfIt If this is all the data (true) or if its split up (false). Default true
+	 * @param bool $reset Does xml parser need to be reset. Default false
 	 * @throws MWException
-	 * @return Boolean success.
+	 * @return bool Success.
 	 */
 	public function parse( $content, $allOfIt = true, $reset = false ) {
 		if ( $reset ) {
@@ -320,7 +331,7 @@ class XMPReader {
 	 * @todo In serious need of testing
 	 * @see http://www.adobe.ge/devnet/xmp/pdfs/XMPSpecificationPart3.pdf XMP spec part 3 page 20
 	 * @param string $content XMPExtended block minus the namespace signature
-	 * @return Boolean If it succeeded.
+	 * @return bool If it succeeded.
 	 */
 	public function parseExtended( $content ) {
 		// @todo FIXME: This is untested. Hard to find example files
@@ -393,7 +404,7 @@ class XMPReader {
 	 * <exif:DigitalZoomRatio>0/10</exif:DigitalZoomRatio>
 	 * and are processing the 0/10 bit.
 	 *
-	 * @param $parser XMLParser reference to the xml parser
+	 * @param XMLParser $parser XMLParser reference to the xml parser
 	 * @param string $data Character data
 	 * @throws MWException on invalid data
 	 */
@@ -452,7 +463,7 @@ class XMPReader {
 	 * Or it could be if we hit the end element of a property
 	 * of a compound data structure (like a member of an array).
 	 *
-	 * @param string $elm namespace, space, and tag name.
+	 * @param string $elm Namespace, space, and tag name.
 	 */
 	private function endElementModeSimple( $elm ) {
 		if ( $this->charContent !== false ) {
@@ -486,7 +497,7 @@ class XMPReader {
 	 *
 	 * This method is called when we hit the "</exif:ISOSpeedRatings>" tag.
 	 *
-	 * @param string $elm namespace . space . tag name.
+	 * @param string $elm Namespace . space . tag name.
 	 * @throws MWException
 	 */
 	private function endElementNested( $elm ) {
@@ -553,7 +564,7 @@ class XMPReader {
 	 * (For comparison, we call endElementModeSimple when we
 	 * hit the "</rdf:li>")
 	 *
-	 * @param string $elm namespace . ' ' . element name
+	 * @param string $elm Namespace . ' ' . element name
 	 * @throws MWException
 	 */
 	private function endElementModeLi( $elm ) {
@@ -593,7 +604,7 @@ class XMPReader {
 	 * Qualifiers aren't all that common, and we don't do anything
 	 * with them.
 	 *
-	 * @param string $elm namespace and element
+	 * @param string $elm Namespace and element
 	 */
 	private function endElementModeQDesc( $elm ) {
 
@@ -617,8 +628,8 @@ class XMPReader {
 	 * Ignores the outer wrapping elements that are optional in
 	 * xmp and have no meaning.
 	 *
-	 * @param $parser XMLParser
-	 * @param string $elm namespace . ' ' . element name
+	 * @param XMLParser $parser
+	 * @param string $elm Namespace . ' ' . element name
 	 * @throws MWException
 	 */
 	function endElement( $parser, $elm ) {
@@ -701,7 +712,7 @@ class XMPReader {
 	 * in which case we add it to the item stack, so we can ignore things
 	 * that are nested, correctly.
 	 *
-	 * @param string $elm namespace . ' ' . tag name
+	 * @param string $elm Namespace . ' ' . tag name
 	 */
 	private function startElementModeIgnore( $elm ) {
 		if ( $elm === $this->curItem[0] ) {
@@ -714,7 +725,7 @@ class XMPReader {
 	 *  Start element in MODE_BAG (unordered array)
 	 * this should always be <rdf:Bag>
 	 *
-	 * @param string $elm namespace . ' ' . tag
+	 * @param string $elm Namespace . ' ' . tag
 	 * @throws MWException if we have an element that's not <rdf:Bag>
 	 */
 	private function startElementModeBag( $elm ) {
@@ -729,7 +740,7 @@ class XMPReader {
 	 * Start element in MODE_SEQ (ordered array)
 	 * this should always be <rdf:Seq>
 	 *
-	 * @param string $elm namespace . ' ' . tag
+	 * @param string $elm Namespace . ' ' . tag
 	 * @throws MWException if we have an element that's not <rdf:Seq>
 	 */
 	private function startElementModeSeq( $elm ) {
@@ -756,7 +767,7 @@ class XMPReader {
 	 * which are really only used for thumbnails, which
 	 * we don't care about.
 	 *
-	 * @param string $elm namespace . ' ' . tag
+	 * @param string $elm Namespace . ' ' . tag
 	 * @throws MWException if we have an element that's not <rdf:Alt>
 	 */
 	private function startElementModeLang( $elm ) {
@@ -781,7 +792,7 @@ class XMPReader {
 	 *
 	 * This method is called when processing the <rdf:Description> element
 	 *
-	 * @param string $elm namespace and tag names separated by space.
+	 * @param string $elm Namespace and tag names separated by space.
 	 * @param array $attribs Attributes of the element.
 	 * @throws MWException
 	 */
@@ -819,7 +830,7 @@ class XMPReader {
 	 *   </exif:DigitalZoomRatio>
 	 * Called when processing the <rdf:value> or <foo:someQualifier>.
 	 *
-	 * @param string $elm namespace and tag name separated by a space.
+	 * @param string $elm Namespace and tag name separated by a space.
 	 *
 	 */
 	private function startElementModeQDesc( $elm ) {
@@ -901,9 +912,9 @@ class XMPReader {
 	 * <exif:Flash rdf:parseType='Resource'> <exif:Fired>True</exif:Fired>
 	 *  <exif:Mode>1</exif:Mode></exif:Flash>
 	 *
-	 * @param string $ns namespace
-	 * @param string $tag tag name (no ns)
-	 * @param array $attribs array of attribs w/ values.
+	 * @param string $ns Namespace
+	 * @param string $tag Tag name (no ns)
+	 * @param array $attribs Array of attribs w/ values.
 	 * @throws MWException
 	 */
 	private function startElementModeStruct( $ns, $tag, $attribs ) {
@@ -950,7 +961,7 @@ class XMPReader {
 	 *   </rdf:Seq> </exif:ISOSpeedRatings>
 	 * This method is called when we hit the <rdf:li> element.
 	 *
-	 * @param string $elm namespace . ' ' . tagname
+	 * @param string $elm Namespace . ' ' . tagname
 	 * @param array $attribs Attributes. (needed for BAGSTRUCTS)
 	 * @throws MWException if gets a tag other than <rdf:li>
 	 */
@@ -1000,9 +1011,9 @@ class XMPReader {
 	 *
 	 * This method is called when we hit the <rdf:li> element.
 	 *
-	 * @param string $elm namespace . ' ' . tag
-	 * @param array $attribs array of elements (most importantly xml:lang)
-	 * @throws MWException if gets a tag other than <rdf:li> or if no xml:lang
+	 * @param string $elm Namespace . ' ' . tag
+	 * @param array $attribs Array of elements (most importantly xml:lang)
+	 * @throws MWException If gets a tag other than <rdf:li> or if no xml:lang
 	 */
 	private function startElementModeLiLang( $elm, $attribs ) {
 		if ( $elm !== self::NS_RDF . ' li' ) {
@@ -1031,8 +1042,8 @@ class XMPReader {
 	 * Also does some initial set up for the wrapper element
 	 *
 	 * @param $parser XMLParser
-	 * @param string $elm namespace "<space>" element
-	 * @param array $attribs attribute name => value
+	 * @param string $elm Namespace "<space>" element
+	 * @param array $attribs Attribute name => value
 	 * @throws MWException
 	 */
 	function startElement( $parser, $elm, $attribs ) {
@@ -1124,7 +1135,7 @@ class XMPReader {
 	 * <rdf:Description rdf:about="" xmlns:exif="http://ns.adobe.com/exif/1.0/" exif:DigitalZoomRatio="0/10">
 	 * @endcode
 	 *
-	 * @param array $attribs attribute=>value array.
+	 * @param array $attribs Array attribute=>value
 	 * @throws MWException
 	 */
 	// @codingStandardsIgnoreEnd
@@ -1173,9 +1184,9 @@ class XMPReader {
 	 * $this->processingArray to determine what name to
 	 * save the value under. (in addition to $tag).
 	 *
-	 * @param string $ns namespace of tag this is for
-	 * @param string $tag tag name
-	 * @param string $val value to save
+	 * @param string $ns Namespace of tag this is for
+	 * @param string $tag Tag name
+	 * @param string $val Value to save
 	 */
 	private function saveValue( $ns, $tag, $val ) {
 
diff --git a/includes/media/XMPInfo.php b/includes/media/XMPInfo.php
index d57af5d20c..3272fef4cf 100644
--- a/includes/media/XMPInfo.php
+++ b/includes/media/XMPInfo.php
@@ -27,8 +27,8 @@
  * extract.
  */
 class XMPInfo {
-	/** get the items array
-	 * @return Array XMP item configuration array.
+	/** Get the items array
+	 * @return array XMP item configuration array.
 	 */
 	public static function getItems() {
 		if ( !self::$ranHooks ) {
@@ -66,7 +66,7 @@ class XMPInfo {
 	 *     * children - for MODE_STRUCT items, allowed children.
 	 *   * structPart - Indicates that this element can only appear as a member of a structure.
 	 *
-	 * currently this just has a bunch of exif values as this class is only half-done
+	 * Currently this just has a bunch of exif values as this class is only half-done
 	 */
 	static private $items = array(
 		'http://ns.adobe.com/exif/1.0/' => array(
diff --git a/includes/media/XMPValidate.php b/includes/media/XMPValidate.php
index 8919601d42..43622179df 100644
--- a/includes/media/XMPValidate.php
+++ b/includes/media/XMPValidate.php
@@ -42,11 +42,11 @@
  */
 class XMPValidate {
 	/**
-	 * function to validate boolean properties ( True or False )
+	 * Function to validate boolean properties ( True or False )
 	 *
-	 * @param array $info information about current property
-	 * @param &$val Mixed current value to validate
-	 * @param $standalone Boolean if this is a simple property or array
+	 * @param array $info Information about current property
+	 * @param mixed &$val Current value to validate
+	 * @param bool $standalone If this is a simple property or array
 	 */
 	public static function validateBoolean( $info, &$val, $standalone ) {
 		if ( !$standalone ) {
@@ -62,9 +62,9 @@ class XMPValidate {
 	/**
 	 * function to validate rational properties ( 12/10 )
 	 *
-	 * @param array $info information about current property
-	 * @param &$val Mixed current value to validate
-	 * @param $standalone Boolean if this is a simple property or array
+	 * @param array $info Information about current property
+	 * @param mixed &$val Current value to validate
+	 * @param bool $standalone If this is a simple property or array
 	 */
 	public static function validateRational( $info, &$val, $standalone ) {
 		if ( !$standalone ) {
@@ -83,9 +83,9 @@ class XMPValidate {
 	 * if its outside of range put it into range.
 	 *
 	 * @see MWG spec
-	 * @param array $info information about current property
-	 * @param &$val Mixed current value to validate
-	 * @param $standalone Boolean if this is a simple property or array
+	 * @param array $info Information about current property
+	 * @param mixed &$val Current value to validate
+	 * @param bool $standalone If this is a simple property or array
 	 */
 	public static function validateRating( $info, &$val, $standalone ) {
 		if ( !$standalone ) {
@@ -122,9 +122,9 @@ class XMPValidate {
 	/**
 	 * function to validate integers
 	 *
-	 * @param array $info information about current property
-	 * @param &$val Mixed current value to validate
-	 * @param $standalone Boolean if this is a simple property or array
+	 * @param array $info Information about current property
+	 * @param mixed &$val Current value to validate
+	 * @param bool $standalone If this is a simple property or array
 	 */
 	public static function validateInteger( $info, &$val, $standalone ) {
 		if ( !$standalone ) {
@@ -141,9 +141,9 @@ class XMPValidate {
 	 * function to validate properties with a fixed number of allowed
 	 * choices. (closed choice)
 	 *
-	 * @param array $info information about current property
+	 * @param array $info Information about current property
 	 * @param &$val Mixed current value to validate
-	 * @param $standalone Boolean if this is a simple property or array
+	 * @param bool $standalone If this is a simple property or array
 	 */
 	public static function validateClosed( $info, &$val, $standalone ) {
 		if ( !$standalone ) {
@@ -171,9 +171,9 @@ class XMPValidate {
 	/**
 	 * function to validate and modify flash structure
 	 *
-	 * @param array $info information about current property
+	 * @param array $info Information about current property
 	 * @param &$val Mixed current value to validate
-	 * @param $standalone Boolean if this is a simple property or array
+	 * @param bool $standalone If this is a simple property or array
 	 */
 	public static function validateFlash( $info, &$val, $standalone ) {
 		if ( $standalone ) {
@@ -205,9 +205,9 @@ class XMPValidate {
 	 * @see rfc 3066
 	 * @see http://www.adobe.com/devnet/xmp/pdfs/XMPSpecificationPart1.pdf page 30 (section 8.2.2.5)
 	 *
-	 * @param array $info information about current property
+	 * @param array $info Information about current property
 	 * @param &$val Mixed current value to validate
-	 * @param $standalone Boolean if this is a simple property or array
+	 * @param bool $standalone If this is a simple property or array
 	 */
 	public static function validateLangCode( $info, &$val, $standalone ) {
 		if ( !$standalone ) {
@@ -232,11 +232,11 @@ class XMPValidate {
 	 * YYYY-MM-DDThh:mm:ssTZD
 	 * YYYY-MM-DDThh:mm:ss.sTZD
 	 *
-	 * @param array $info information about current property
-	 * @param &$val Mixed current value to validate. Converts to TS_EXIF as a side-effect.
+	 * @param array $info Information about current property
+	 * @param mixed &$val Current value to validate. Converts to TS_EXIF as a side-effect.
 	 *    in cases where there's only a partial date, it will give things like
 	 *    2011:04.
-	 * @param $standalone Boolean if this is a simple property or array
+	 * @param bool $standalone If this is a simple property or array
 	 */
 	public static function validateDate( $info, &$val, $standalone ) {
 		if ( !$standalone ) {
@@ -334,10 +334,10 @@ class XMPValidate {
 	 * @see http://www.adobe.com/devnet/xmp/pdfs/XMPSpecificationPart2.pdf
 	 *        section 1.2.7.4 on page 23
 	 *
-	 * @param array $info unused (info about prop)
-	 * @param &$val String GPS string in either DDD,MM,SSk or
-	 *           or DDD,MM.mmk form
-	 * @param $standalone Boolean if its a simple prop (should always be true)
+	 * @param array $info Unused (info about prop)
+	 * @param string &$val GPS string in either DDD,MM,SSk or
+	 *   or DDD,MM.mmk form
+	 * @param bool $standalone If its a simple prop (should always be true)
 	 */
 	public static function validateGPS( $info, &$val, $standalone ) {
 		if ( !$standalone ) {
-- 
2.20.1