jenkins-bot has submitted this change and it was merged. (
https://gerrit.wikimedia.org/r/384231 )
Change subject: Improve some parameter docs
......................................................................
Improve some parameter docs
Change-Id: Ia4780a1e3bb2c9e6b53565a31c4003fc650bab36
---
M PagedTiffHandler.image.php
M PagedTiffHandler_body.php
M phpcs.xml
3 files changed, 86 insertions(+), 42 deletions(-)
Approvals:
jenkins-bot: Verified
Jforrester: Looks good to me, approved
diff --git a/PagedTiffHandler.image.php b/PagedTiffHandler.image.php
index c645dc3..6e12d1b 100644
--- a/PagedTiffHandler.image.php
+++ b/PagedTiffHandler.image.php
@@ -36,6 +36,7 @@
/**
* Called by MimeMagick functions.
+ * @return int
*/
public function isValid() {
return count( $this->retrieveMetaData() );
@@ -43,6 +44,7 @@
/**
* Returns an array that corresponds to the native PHP function
getimagesize().
+ * @return array|false
*/
public function getImageSize() {
$data = $this->retrieveMetaData();
@@ -59,6 +61,9 @@
/**
* Returns an array with width and height of the tiff page.
+ * @param array $data
+ * @param int $page
+ * @return array|false
*/
public static function getPageSize( $data, $page ) {
if ( isset( $data['page_data'][$page] ) ) {
@@ -76,7 +81,7 @@
/**
* Reads metadata of the tiff file via shell command and returns an
associative array.
- * layout:
+ * @return array Associative array. Layout:
* meta['page_count'] = number of pages
* meta['first_page'] = number of first page
* meta['last_page'] = number of last page
@@ -202,6 +207,8 @@
/**
* helper function of retrieveMetaData().
* parses shell return from tiffinfo-command into an array.
+ * @param string $dump
+ * @return array
*/
protected function parseTiffinfoOutput( $dump ) {
global $wgTiffTiffinfoRejectMessages,
$wgTiffTiffinfoBypassMessages;
@@ -320,6 +327,8 @@
/**
* helper function of retrieveMetaData().
* parses shell return from exiv2-command into an array.
+ * @param string $dump
+ * @return array
*/
protected function parseExiv2Output( $dump ) {
$result = [];
@@ -337,6 +346,8 @@
/**
* helper function of retrieveMetaData().
* parses shell return from identify-command into an array.
+ * @param string $dump
+ * @return array
*/
protected function parseIdentifyOutput( $dump ) {
global $wgTiffIdentifyRejectMessages,
$wgTiffIdentifyBypassMessages;
diff --git a/PagedTiffHandler_body.php b/PagedTiffHandler_body.php
index 7dc6ef2..0d5bc62 100644
--- a/PagedTiffHandler_body.php
+++ b/PagedTiffHandler_body.php
@@ -41,6 +41,7 @@
}
/**
+ * @param File $img
* @return bool
*/
function mustRender( $img ) {
@@ -49,6 +50,8 @@
/**
* Does the file format support multi-page documents?
+ * @param File $img
+ * @return bool
*/
function isMultiPage( $img ) {
return true;
@@ -62,6 +65,8 @@
* - identify-errors
* - identify-warnings
* - check for running-identify-service
+ * @param string $fileName
+ * @return Status
*/
function verifyUpload( $fileName ) {
global $wgTiffUseTiffReader, $wgTiffReaderCheckEofForJS;
@@ -101,8 +106,8 @@
}
/**
- * @param $meta array
- * @param $error array
+ * @param array $meta
+ * @param array &$error
* @return bool
*/
static function verifyMetaData( $meta, &$error ) {
@@ -141,6 +146,7 @@
/**
* Maps MagicWord-IDs to parameters.
* In this case, width, page, and lossy.
+ * @return array
*/
function getParamMap() {
return [
@@ -153,6 +159,9 @@
/**
* Checks whether parameters are valid and have valid values.
* Check for lossy was added.
+ * @param string $name
+ * @param string $value
+ * @return bool
*/
function validateParam( $name, $value ) {
if ( in_array( $name, [ 'width', 'height', 'page', 'lossy' ] )
) {
@@ -189,6 +198,8 @@
/**
* Creates parameter string for file name.
* Page number was added.
+ * @param array $params
+ * @return string|false
*/
function makeParamString( $params ) {
if (
@@ -202,6 +213,8 @@
/**
* Parses parameter string into an array.
+ * @param string $str
+ * @return array|false
*/
function parseParamString( $str ) {
$m = false;
@@ -213,11 +226,13 @@
}
/**
- * The function is used to specify which parameters to File::transform()
should be
- * passed through to thumb.php, in the case where the configuration
specifies
- * thumb.php is to be used (e.g. $wgThumbnailScriptPath !== false). You
should
- * pass through the same parameters as in makeParamString().
- */
+ * The function is used to specify which parameters to
File::transform() should be
+ * passed through to thumb.php, in the case where the configuration
specifies
+ * thumb.php is to be used (e.g. $wgThumbnailScriptPath !== false). You
should
+ * pass through the same parameters as in makeParamString().
+ * @param array $params
+ * @return array
+ */
function getScriptParams( $params ) {
return [
'width' => $params['width'],
@@ -229,6 +244,9 @@
/**
* Prepares param array and sets standard values.
* Adds normalisation for parameter "lossy".
+ * @param File $image
+ * @param array &$params
+ * @return array
*/
function normaliseParams( $image, &$params ) {
if ( isset( $params['page'] ) ) {
@@ -261,7 +279,7 @@
}
/**
- * @param $metadata array
+ * @param array $metadata
* @return bool|string[] a list of errors or an error flag (true =
error)
*/
static function getMetadataErrors( $metadata ) {
@@ -293,8 +311,8 @@
}
/**
- * @param $errors_raw array
- * @param $to_html bool
+ * @param array $errors_raw
+ * @param bool $to_html
* @return bool|string
*/
static function joinMessages( $errors_raw, $to_html = true ) {
@@ -336,8 +354,8 @@
* What method to use to scale this file
*
* @see TransformationalImageHandler::getScalerType
- * @param $dstPath string Path to store thumbnail
- * @param $checkDstPath boolean Whether to verify destination path
exists
+ * @param string $dstPath Path to store thumbnail
+ * @param bool $checkDstPath Whether to verify destination path exists
* @return Callable Transform function to call.
*/
protected function getScalerType( $dstPath, $checkDstPath = true ) {
@@ -419,9 +437,9 @@
/**
* Get the thumbnail extension and MIME type for a given source MIME
type
- * @param $ext
- * @param $mime
- * @param $params array
+ * @param string $ext
+ * @param string $mime
+ * @param array $params
* @return array thumbnail extension and MIME type
*/
function getThumbType( $ext, $mime, $params = null ) {
@@ -441,6 +459,8 @@
/**
* Returns the number of available pages/embedded files
+ * @param File $image
+ * @return int
*/
function pageCount( File $image ) {
$data = $this->getMetaArray( $image );
@@ -453,6 +473,8 @@
/**
* Returns the number of the first page in the file
+ * @param File $image
+ * @return int
*/
function firstPage( $image ) {
$data = $this->getMetaArray( $image );
@@ -464,6 +486,8 @@
/**
* Returns the number of the last page in the file
+ * @param File $image
+ * @return int
*/
function lastPage( $image ) {
$data = $this->getMetaArray( $image );
@@ -475,6 +499,9 @@
/**
* Returns a page number within range.
+ * @param File $image
+ * @param int|string $page
+ * @return int
*/
function adjustPage( $image, $page ) {
$page = intval( $page );
@@ -492,6 +519,9 @@
/**
* Returns a new error message.
+ * @param array $params
+ * @param string $msg
+ * @return string
*/
protected function doThumbError( $params, $msg ) {
global $wgUser, $wgThumbLimits;
@@ -524,8 +554,8 @@
/**
* Get handler-specific metadata which will be saved in the
img_metadata field.
*
- * @param $image File|bool: the image object, or false if there isn't
one
- * @param $path String: path to the image?
+ * @param File|bool $image the image object, or false if there isn't one
+ * @param string $path path to the image?
* @return string
*/
function getMetadata( $image, $path ) {
@@ -542,6 +572,8 @@
/**
* Creates detail information that is being displayed on image page.
+ * @param File $image
+ * @return string
*/
function getLongDesc( $image ) {
global $wgLang, $wgRequest;
@@ -575,6 +607,9 @@
/**
* Check if the metadata string is valid for this handler.
* If it returns false, Image will reload the metadata from the file
and update the database
+ * @param File $image
+ * @param array $metadata
+ * @return bool
*/
function isMetadataValid( $image, $metadata ) {
if ( is_string( $metadata ) ) {
@@ -602,21 +637,21 @@
* Get an array structure that looks like this:
*
* [
- * 'visible' => [
- * 'Human-readable name' => 'Human readable value',
- * ...
- * ],
- * 'collapsed' => [
- * 'Human-readable name' => 'Human readable value',
- * ...
- * ]
+ * 'visible' => [
+ * 'Human-readable name' => 'Human readable value',
+ * ...
+ * ],
+ * 'collapsed' => [
+ * 'Human-readable name' => 'Human readable value',
+ * ...
+ * ]
* ]
* The UI will format this into a table where the visible fields are
always
* visible, and the collapsed fields are optionally visible.
*
* The function should return false if there is no metadata to display.
*
- * @param $image File
+ * @param File $image
* @param bool|IContextSource $context Context to use (optional)
* @return array|bool
*/
@@ -675,8 +710,8 @@
/**
* Returns a PagedTiffImage or creates a new one if it doesn't exist.
- * @param $image File|bool: The image object, or false if there isn't
one
- * @param $path String: path to the image?
+ * @param File|bool $image The image object, or false if there isn't one
+ * @param string $path path to the image?
* @return PagedTiffImage
*/
static function getTiffImage( $image, $path ) {
@@ -697,7 +732,7 @@
/**
* Returns an Array with the Image metadata.
*
- * @param $image File
+ * @param File $image
* @return bool|null|array
*/
function getMetaArray( $image ) {
@@ -725,7 +760,9 @@
* Get an associative array of page dimensions
* Currently "width" and "height" are understood, but this might be
* expanded in the future.
- * Returns false if unknown or if the document is not multi-page.
+ * @param File $image
+ * @param int $page
+ * @return int|false Returns false if unknown or if the document is not
multi-page.
*/
function getPageDimensions( File $image, $page ) {
// makeImageLink (Linker.php) sets $page to false if no page
parameter
@@ -746,9 +783,9 @@
* advantage of the fact that VIPS can scale integer shrink factors
* much more efficiently than non-integral scaling factors.
*
- * @param $file File
- * @param $params Array Parameters to transform file with.
- * @return Array Array with keys path, width and height
+ * @param File $file
+ * @param array $params Parameters to transform file with.
+ * @return array Array with keys path, width and height
*/
protected function getThumbnailSource( $file, $params ) {
/** @var MediaTransformOutput */
@@ -775,8 +812,8 @@
* to further scale things down. Size is chosen to be
* efficient to scale in vips for those who use VipsScaler
*
- * @param $file File
- * @param $params Array Scaling parameters for original thumbnail
+ * @param File $file
+ * @param array $params Scaling parameters for original thumbnail
* @return MediaTransformObject|bool false if no in between step needed,
* MediaTransformError on error. False if the doTransform method
returns false
* MediaTransformOutput on success.
@@ -850,7 +887,7 @@
}
/**
- * @param $files array
+ * @param array &$files
* @return bool
*/
public static function onUnitTestsList( &$files ) {
diff --git a/phpcs.xml b/phpcs.xml
index 6d661fa..ce19c05 100644
--- a/phpcs.xml
+++ b/phpcs.xml
@@ -2,9 +2,7 @@
<ruleset>
<rule ref="./vendor/mediawiki/mediawiki-codesniffer/MediaWiki">
<exclude name="Generic.Classes.DuplicateClassName.Found" />
- <exclude
name="MediaWiki.Commenting.FunctionComment.MissingParamName" />
- <exclude
name="MediaWiki.Commenting.FunctionComment.MissingParamTag" />
- <exclude
name="MediaWiki.Commenting.FunctionComment.MissingReturn" />
+ <exclude
name="MediaWiki.Commenting.FunctionComment.MissingParamComment" />
<exclude name="MediaWiki.Files.ClassMatchesFilename.NotMatch" />
<exclude name="MediaWiki.Files.OneClassPerFile.MultipleFound" />
<exclude
name="MediaWiki.Commenting.FunctionComment.MissingDocumentationProtected" />
@@ -14,6 +12,4 @@
<file>.</file>
<arg name="extensions" value="php,php5,inc" />
<arg name="encoding" value="UTF-8" />
- <exclude-pattern>vendor</exclude-pattern>
- <exclude-pattern>node_modules</exclude-pattern>
</ruleset>
--
To view, visit https://gerrit.wikimedia.org/r/384231
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: merged
Gerrit-Change-Id: Ia4780a1e3bb2c9e6b53565a31c4003fc650bab36
Gerrit-PatchSet: 1
Gerrit-Project: mediawiki/extensions/PagedTiffHandler
Gerrit-Branch: master
Gerrit-Owner: Umherirrender <umherirrender_de...@web.de>
Gerrit-Reviewer: Jforrester <jforres...@wikimedia.org>
Gerrit-Reviewer: jenkins-bot <>
_______________________________________________
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
