Method documentation etc

Change-Id: I8b9d111fcce6ce46fd85a128ad21ce523064ab31

CreatePdfThumbnailsJob.class.php

@@ -10,8 +10,8 @@ class CreatePdfThumbnailsJob extends Job {
 	/**
 	 * Construct a thumbnail job
 	 *
-	 * @param $title Title: Title object
-	 * @param $params Associative array of options:
+	 * @param $title Title Title object
+	 * @param $params array Associative array of options:
 	 *     page:           page number for which the thumbnail will be created
 	 *     jobtype:        CreatePDFThumbnailsJob::BIG_THUMB or CreatePDFThumbnailsJob::SMALL_THUMB
 	 *                     BIG_THUMB will create a thumbnail visible for full thumbnail view,
@@ -62,12 +62,12 @@ class CreatePdfThumbnailsJob extends Job {
 					# Calculate the thumbnail size.
 					# First case, the limiting factor is the width, not the height.
 					if ( $width / $height >= $maxWidth / $maxHeight ) {
-						$height = round( $height * $maxWidth / $width );
+						//$height = round( $height * $maxWidth / $width );
 						$width = $maxWidth;
 						# Note that $height <= $maxHeight now.
 					} else {
 						$newwidth = floor( $width * $maxHeight / $height );
-						$height = round( $height * $newwidth / $width );
+						//$height = round( $height * $newwidth / $width );
 						$width = $newwidth;
 						# Note that $height <= $maxHeight now, but might not be identical
 						# because of rounding.
@@ -78,9 +78,7 @@ class CreatePdfThumbnailsJob extends Job {
 				break;
 
 			case self::SMALL_THUMB:
-				global $wgUser;
-				$sk = $wgUser->getSkin();
-				$sk->makeThumbLinkObj( $this->title, $file, '', '', 'none', array( 'page' => $this->params['page'] ) );
+				Linker::makeThumbLinkObj( $this->title, $file, '', '', 'none', array( 'page' => $this->params['page'] ) );
 				break;
 		}
 
@@ -88,7 +86,7 @@ class CreatePdfThumbnailsJob extends Job {
 	}
 
 	/**
-	 * @param $upload
+	 * @param $upload UploadBase
 	 * @param $mime
 	 * @param $error
 	 * @return bool
@@ -104,7 +102,7 @@ class CreatePdfThumbnailsJob extends Job {
 
 		$title = $upload->getTitle();
 		$uploadFile = $upload->getLocalFile();
-		if ( is_null($uploadFile) ) {
+		if ( is_null( $uploadFile ) ) {
 			wfDebugLog('thumbnails', '$uploadFile seems to be null, should never happen...');
 			return true; // should never happen, but it's better to be secure
 		}
@@ -114,7 +112,7 @@ class CreatePdfThumbnailsJob extends Job {
 		$pages = intval( $unserialized['Pages'] );
 
 		$jobs = array();
-		for ($i = 1; $i <= $pages; $i++) {
+		for ( $i = 1; $i <= $pages; $i++ ) {
 			$jobs[] = new CreatePdfThumbnailsJob( $title, 
 								array( 'page' => $i, 'jobtype' => self::BIG_THUMB )
 							);

PdfHandler.i18n.php

@@ -20,6 +20,8 @@ $messages['en'] = array(
  */
 $messages['qqq'] = array(
 	'pdf-desc' => '{{desc}}',
+	'pdf_no_metadata' => 'Error message given when metadata cannot be retrieved from a PDF file',
+	'pdf_page_error' => 'Error message given when a PDF does not have the requested page number',
 );
 
 /** Afrikaans (Afrikaans)

PdfHandler.php

@@ -32,7 +32,7 @@ if ( !defined( 'MEDIAWIKI' ) ) {
 $wgExtensionCredits['media'][] = array(
 	'path' => __FILE__,
 	'name' => 'PDF Handler',
-	'author' => array( 'Martin Seidel', 'Mike Połtyn'),
+	'author' => array( 'Martin Seidel', 'Mike Połtyn' ),
 	'descriptionmsg' => 'pdf-desc',
 	'url' => 'https://www.mediawiki.org/wiki/Extension:PdfHandler',
 );

PdfHandler_body.php

@@ -23,6 +23,9 @@
 
 class PdfHandler extends ImageHandler {
 
+	/**
+	 * @return bool
+	 */
 	function isEnabled() {
 		global $wgPdfProcessor, $wgPdfPostProcessor, $wgPdfInfo;
 
@@ -35,14 +38,27 @@ class PdfHandler extends ImageHandler {
 		return true;
 	}
 
+	/**
+	 * @param $file
+	 * @return bool
+	 */
 	function mustRender( $file ) {
 		return true;
 	}
 
+	/**
+	 * @param $file
+	 * @return bool
+	 */
 	function isMultiPage( $file ) {
 		return true;
 	}
 
+	/**
+	 * @param $name
+	 * @param $value
+	 * @return bool
+	 */
 	function validateParam( $name, $value ) {
 		if ( in_array( $name, array( 'width', 'height', 'page' ) ) ) {
 			return ( $value <= 0 ) ? false : true;
@@ -51,6 +67,10 @@ class PdfHandler extends ImageHandler {
 		}
 	}
 
+	/**
+	 * @param $params array
+	 * @return bool|string
+	 */
 	function makeParamString( $params ) {
 		$page = isset( $params['page'] ) ? $params['page'] : 1;
 		if ( !isset( $params['width'] ) ) {
@@ -59,6 +79,10 @@ class PdfHandler extends ImageHandler {
 		return "page{$page}-{$params['width']}px";
 	}
 
+	/**
+	 * @param $str string
+	 * @return array|bool
+	 */
 	function parseParamString( $str ) {
 		$m = false;
 
@@ -69,6 +93,10 @@ class PdfHandler extends ImageHandler {
 		return false;
 	}
 
+	/**
+	 * @param $params array
+	 * @return array
+	 */
 	function getScriptParams( $params ) {
 		return array(
 			'width' => $params['width'],
@@ -76,6 +104,9 @@ class PdfHandler extends ImageHandler {
 		);
 	}
 
+	/**
+	 * @return array
+	 */
 	function getParamMap() {
 		return array(
 			'img_width' => 'width',
@@ -83,11 +114,25 @@ class PdfHandler extends ImageHandler {
 		);
 	}
 
+	/**
+	 * @param $width
+	 * @param $height
+	 * @param $msg
+	 * @return MediaTransformError
+	 */
 	protected function doThumbError( $width, $height, $msg ) {
 		return new MediaTransformError( 'thumbnail_error',
 			$width, $height, wfMsgForContent( $msg ) );
 	}
 
+	/**
+	 * @param $image File
+	 * @param $dstPath string
+	 * @param $dstUrl string
+	 * @param $params array
+	 * @param $flags int
+	 * @return MediaTransformError|MediaTransformOutput|ThumbnailImage|TransformParameterError
+	 */
 	function doTransform( $image, $dstPath, $dstUrl, $params, $flags = 0 ) {
 		global $wgPdfProcessor, $wgPdfPostProcessor, $wgPdfHandlerDpi;
 
@@ -145,6 +190,11 @@ class PdfHandler extends ImageHandler {
 		}
 	}
 
+	/**
+	 * @param $image File
+	 * @param $path string
+	 * @return PdfImage
+	 */
 	function getPdfImage( $image, $path ) {
 		if ( !$image ) {
 			$pdfimg = new PdfImage( $path );
@@ -157,6 +207,10 @@ class PdfHandler extends ImageHandler {
 		return $pdfimg;
 	}
 
+	/**
+	 * @param $image File
+	 * @return bool
+	 */
 	function getMetaArray( $image ) {
 		if ( isset( $image->pdfMetaArray ) ) {
 			return $image->pdfMetaArray;
@@ -178,10 +232,21 @@ class PdfHandler extends ImageHandler {
 		return $image->pdfMetaArray;
 	}
 
+	/**
+	 * @param $image File
+	 * @param $path string
+	 * @return array|bool
+	 */
 	function getImageSize( $image, $path ) {
 		return $this->getPdfImage( $image, $path )->getImageSize();
 	}
 
+	/**
+	 * @param $ext
+	 * @param $mime string
+	 * @param $params null
+	 * @return array
+	 */
 	function getThumbType( $ext, $mime, $params = null ) {
 		global $wgPdfOutputExtension;
 		static $mime;
@@ -193,14 +258,28 @@ class PdfHandler extends ImageHandler {
 		return array( $wgPdfOutputExtension, $mime );
 	}
 
+	/**
+	 * @param $image File
+	 * @param $path string
+	 * @return string
+	 */
 	function getMetadata( $image, $path ) {
 		return serialize( $this->getPdfImage( $image, $path )->retrieveMetaData() );
 	}
 
+	/**
+	 * @param $image File
+	 * @param $metadata string
+	 * @return bool
+	 */
 	function isMetadataValid( $image, $metadata ) {
 		return !empty( $metadata ) && $metadata != serialize( array() );
 	}
 
+	/**
+	 * @param $image File
+	 * @return bool|int
+	 */
 	function pageCount( $image ) {
 		$data = $this->getMetaArray( $image );
 		if ( !$data ) {
@@ -209,11 +288,21 @@ class PdfHandler extends ImageHandler {
 		return intval( $data['Pages'] );
 	}
 
+	/**
+	 * @param $image File
+	 * @param $page int
+	 * @return array|bool
+	 */
 	function getPageDimensions( $image, $page ) {
 		$data = $this->getMetaArray( $image );
 		return PdfImage::getPageSize( $data, $page );
 	}
 
+	/**
+	 * @param $image File
+	 * @param $page int
+	 * @return bool
+	 */
 	function getPageText( $image, $page ) {
 		$data = $this->getMetaArray( $image, true );
 		if ( !$data ) {