Welterkj has submitted this change and it was merged. (
https://gerrit.wikimedia.org/r/402651 )
Change subject: Improve some parameter docs
......................................................................
Improve some parameter docs
Change-Id: I3ff96ec363776a12be0cc5247b3de74d172c6bd9
---
M .phpcs.xml
M includes/GraphViz.php
M includes/UploadFromLocalFile.php
M includes/UploadLocalFile.php
4 files changed, 98 insertions(+), 54 deletions(-)
Approvals:
Welterkj: Verified; Looks good to me, approved
Samwilson: Looks good to me, but someone else must approve
diff --git a/.phpcs.xml b/.phpcs.xml
index f9408cd..6cbe822 100644
--- a/.phpcs.xml
+++ b/.phpcs.xml
@@ -6,8 +6,6 @@
<exclude name="Generic.Files.LineLength.TooLong" />
<exclude
name="MediaWiki.Commenting.FunctionComment.MissingDocumentationPublic" />
<exclude
name="MediaWiki.Commenting.FunctionComment.MissingParamComment" />
- <exclude
name="MediaWiki.Commenting.FunctionComment.MissingParamTag" />
- <exclude
name="MediaWiki.Commenting.FunctionComment.MissingReturn" />
</rule>
<file>.</file>
<arg name="extensions" value="php,php5,inc"/>
diff --git a/includes/GraphViz.php b/includes/GraphViz.php
index c1f5d91..bcfc101 100644
--- a/includes/GraphViz.php
+++ b/includes/GraphViz.php
@@ -185,7 +185,8 @@
/**
* Check if a given image type is probably allowed to be uploaded
* (does not consult any file extension blacklists).
- * @param[in] string $imageType is the type of image (e.g. png) to
check.
+ * @param string $imageType is the type of image (e.g. png) to check.
+ * @return bool
* @author Keith Welter
*/
public static function imageTypeAllowed( $imageType ) {
@@ -201,6 +202,7 @@
/**
* Set parser hook functions for supported graph types.
* @author Keith Welter
+ * @param Parser &$parser
* @return true
*/
public static function onParserInit( Parser &$parser ) {
@@ -213,6 +215,10 @@
/**
* When an article is deleted, delete all the associated graph files.
* @author Keith Welter
+ * @param Article &$article
+ * @param User &$user
+ * @param string $reason
+ * @param int $id
*/
public static function onArticleDeleteComplete( &$article, User &$user,
$reason, $id ) {
self::deleteArticleUploadedFiles( $article, self::getImageDir()
);
@@ -223,6 +229,8 @@
/**
* For a given title, get the corresponding graph file base name.
* @author Keith Welter
+ * @param Title $title
+ * @return string
*/
public static function getGraphFileBaseNameFromTitle( $title ) {
$baseName = $title->getFulltext();
@@ -233,6 +241,8 @@
/**
* Delete all the graph files associated with the given article and
path.
* @author Keith Welter
+ * @param Article $article
+ * @param string $path
*/
public static function deleteArticleFiles( $article, $path ) {
$title = $article->getTitle();
@@ -244,6 +254,8 @@
/**
* Detect if the given title has associated graph files at the given
path.
+ * @param Title $title
+ * @param string $path
* @return True if the title has associated graph files. Otherwise
false.
* @author Keith Welter
*/
@@ -262,6 +274,8 @@
/**
* Delete all uploaded files associated with the given article and path.
* @author Keith Welter
+ * @param Article $article
+ * @param string $path
*/
public static function deleteArticleUploadedFiles( $article, $path ) {
wfDebug( __METHOD__ . ": entering\n" );
@@ -280,6 +294,8 @@
/**
* Delete all the graph files associated with the graph name and path.
* @author Keith Welter
+ * @param string $graphName
+ * @param string $path
*/
public static function deleteGraphFiles( $graphName, $path ) {
$globPattern = $path . $graphName . "*.*";
@@ -293,6 +309,10 @@
* the parser cache reflects the canceled edit rather than the saved
graph so we must
* reject it.
* @author Keith Welter
+ * @param ParserOutput $parserOutput
+ * @param WikiPage $wikiPage
+ * @param ParserOptions $parserOptions
+ * @return bool
*/
public static function onRejectParserCacheValue( $parserOutput,
$wikiPage, $parserOptions ) {
$title = $wikiPage->getTitle();
@@ -313,6 +333,16 @@
* (graph images for which the source wiki text has been deleted).
* Graph images for extant wiki source will be regenerated when parsed.
* @author Keith Welter
+ * @param \WikiPage $wikiPage
+ * @param User $user
+ * @param Content $content
+ * @param string $summary
+ * @param bool $isMinor
+ * @param bool $isWatch
+ * @param string|int $section
+ * @param int $flags
+ * @param Status $status
+ * @return true
*/
public static function onPageContentSave(
\WikiPage $wikiPage, $user, $content,
@@ -329,7 +359,7 @@
}
/**
- * @param[in] string $graphName is the name of the graph to make
"friendly".
+ * @param string $graphName is the name of the graph to make "friendly".
* @return string $graphName with non-alphanumerics replaced with
underscores.
* @author Keith Welter
*/
@@ -343,6 +373,11 @@
* This is a front-end to self::render which does the heavy lifting.
* @see http://www.mcternan.me.uk/mscgen/
* @author Matthew Pearson
+ * @param string $input
+ * @param array $args
+ * @param Parser $parser
+ * @param PPFrame $frame
+ * @return string
*/
public static function mscgenParserHook( $input, $args, $parser, $frame
) {
$args['renderer'] = self::$graphLanguages[self::MSCGEN];
@@ -355,6 +390,11 @@
* This is a front-end to self::render which does the heavy lifting.
* @see http://www.graphviz.org/content/dot-language
* @author Thomas Hummel
+ * @param string $input
+ * @param array $args
+ * @param Parser $parser
+ * @param PPFrame $frame
+ * @return string
*/
public static function graphvizParserHook( $input, $args, $parser,
$frame ) {
if ( isset( $args['renderer'] ) ) {
@@ -459,14 +499,14 @@
* responsibility of the ImageMap extension (as is the case when the
ImageMap extension
* parses links directly from ImageMap tag content).
*
- * @param[in] string $input contains the graph description. URL
attribute values in the graph
+ * @param string $input contains the graph description. URL attribute
values in the graph
* description should be specified as described at
http://en.wikipedia.org/wiki/Help:Link.
* Examples:
* - URL="[[wikilink]]"
* - URL="[[interwiki link]]"
* - URL="[external link]"
*
- * @param[in] array $args contains the graph tag attributes.
Applicable attribute names
+ * @param array $args contains the graph tag attributes. Applicable
attribute names
* are those listed for generateImageMapInput() as well as "uniquifier"
and "format":
* - The optional "uniquifier" attribute value is used to disambiguate
* graphs of the same name or those with no graph name at all. The
mscgen language
@@ -475,7 +515,8 @@
* - The optional "format" attribute allows the user to specify the
image type from
* among those supported for the graph language. @ref Files.
*
- * @param[in] Parser $parser
+ * @param Parser $parser
+ * @param PPFrame $frame
*
* @return string HTML of a graph image and optional map or an HTML
error message.
*
@@ -729,6 +770,9 @@
* @see http://www.graphviz.org/content/attrs#dimagepath
* @see http://www.graphviz.org/content/attrs#dshapefile
* @see http://www.graphviz.org/content/attrs#afontpath
+ * @param string &$input
+ * @param array &$errorText
+ * @return bool
*/
protected static function sanitizeDotInput( &$input, &$errorText ) {
// reject forbidden attributes from the input
@@ -768,7 +812,7 @@
* Ensure a dot image attribute value corresponds to the name of an
uploaded file.
* @return string image attribute name-value pair with the value set to
a validated uploaded
* file name or 'image=""' to indicate an invalid image attribute
value.
- * @param[in] array $matches corresponds to the pattern returned by
GraphViz::getDotImagePattern().
+ * @param array $matches corresponds to the pattern returned by
GraphViz::getDotImagePattern().
* @author Keith Welter
* @see GraphViz::sanitizeDotInput
*/
@@ -805,7 +849,7 @@
* Ensure a dot IMG SRC attribute value corresponds to the name of an
uploaded file.
* @return string IMG SRC attribute name-value pair with the value set
to a validated uploaded
* file name or 'src=""' to indicate an invalid image attribute value.
- * @param[in] array $matches corresponds to GraphViz::DOT_IMG_PATTERN.
+ * @param array $matches corresponds to GraphViz::DOT_IMG_PATTERN.
* @author Keith Welter
* @see GraphViz::sanitizeDotInput
*/
@@ -825,7 +869,7 @@
}
/**
- * @param[in] string $mapPath is the file system path of the graph map
file.
+ * @param string $mapPath is the file system path of the graph map file.
* @return string contents of the given graph map file.
* @author Keith Welter
*/
@@ -845,9 +889,9 @@
/**
* Delete the given graph source, image and map files.
*
- * @param[in] GraphRenderParms $graphParms contains the names of the
graph source, image and map files to delete.
- * @param[in] boolean $userSpecific indicates whether or not the files
to be deleted are user specific.
- * @param[in] boolean $deleteUploads indicates whether or not to delete
the uploaded image file.
+ * @param GraphRenderParms $graphParms contains the names of the graph
source, image and map files to delete.
+ * @param bool $userSpecific indicates whether or not the files to be
deleted are user specific.
+ * @param bool $deleteUploads indicates whether or not to delete the
uploaded image file.
*
* @author Keith Welter
*/
@@ -864,8 +908,8 @@
}
/**
- * @param[in] string $command is the command line to execute.
- * @param[out] string $output is the output of the command.
+ * @param string $command is the command line to execute.
+ * @param string &$output is the output of the command.
* @return bool true upon success, false upon failure.
* @author Keith Welter et al.
*/
@@ -897,10 +941,10 @@
* - [URL description]
* @see
http://www.mediawiki.org/wiki/Extension:ImageMap#Syntax_description
*
- * @param[in] string $mapPath is the map file (including path).
- * @param[in] string $renderer is the name of the renderer used to
produce the map.
- * @param[in] string $pageTitle is the page title to supply for DOT
tooltips that do not have URLs.
- * @param[out] string $errorText is populated with an error message in
the event of an error.
+ * @param string $mapPath is the map file (including path).
+ * @param string $renderer is the name of the renderer used to produce
the map.
+ * @param string $pageTitle is the page title to supply for DOT
tooltips that do not have URLs.
+ * @param string &$errorText is populated with an error message in the
event of an error.
*
* @return bool true upon success, false upon failure.
*
@@ -1006,7 +1050,7 @@
* Convert the input into a syntax acceptable by the ImageMap extension.
* @see
http://www.mediawiki.org/wiki/Extension:ImageMap#Syntax_description
*
- * @param[in] array $args is an optional list of image display
attributes
+ * @param array $args is an optional list of image display attributes
* to be applied to the rendered image. Attribute usage is documented
here:
* http://en.wikipedia.org/wiki/Wikipedia:Extended_image_syntax
* Applicable attributes are:
@@ -1019,8 +1063,8 @@
* - alt
* - caption
*
- * @param[in] string $imageFileName is the filename (without path) of
the graph image to render.
- * @param[in] string $map is map data which is one or more lines each
with the following order:
+ * @param string $imageFileName is the filename (without path) of the
graph image to render.
+ * @param string $map is map data which is one or more lines each with
the following order:
* -# shape name
* -# coordinates
* -# link (see http://en.wikipedia.org/wiki/Help:Link)
@@ -1070,9 +1114,9 @@
/**
* Update the graph source on disk.
*
- * @param[in] string $sourceFilePath is the path of the graph source
file to update.
- * @param[in] string $source is the text to save in $sourceFilePath.
- * @param[out] string $errorText is populated with an error message in
case of error.
+ * @param string $sourceFilePath is the path of the graph source file
to update.
+ * @param string $source is the text to save in $sourceFilePath.
+ * @param string &$errorText is populated with an error message in case
of error.
*
* @return bool true upon success, false upon failure.
*
@@ -1093,11 +1137,11 @@
/**
* Check if the source text matches the contents of the source file.
*
- * @param[in] string $sourceFilePath is the path of existing source in
the file system.
- * @param[in] string $source is the wikitext to be compared with the
contents of $sourceFilePath.
- * @param[out] boolean $sourceChanged is set to true if $source does
not match the contents of $sourceFilePath
+ * @param string $sourceFilePath is the path of existing source in the
file system.
+ * @param string $source is the wikitext to be compared with the
contents of $sourceFilePath.
+ * @param bool &$sourceChanged is set to true if $source does not match
the contents of $sourceFilePath
* (otherwise it is set to false).
- * @param[out] string $errorText is populated with an error message in
case of error.
+ * @param string &$errorText is populated with an error message in case
of error.
*
* @return bool true upon success, false upon failure.
*
@@ -1127,7 +1171,7 @@
/**
* Given a message name, return an HTML error message.
- * @param[in] string $messageName is the name of a message in the i18n
file.
+ * @param string $messageName is the name of a message in the i18n file.
* A variable number of message arguments is supported.
* @return string escaped HTML error message for $messageName.
* @author Keith Welter
@@ -1142,7 +1186,7 @@
}
/**
- * @param[in] string $text is text to be escaped and rendered as an
HTML error.
+ * @param string $text is text to be escaped and rendered as an HTML
error.
* @return string HTML escaped and rendered as an error.
* @author Keith Welter
*/
@@ -1151,7 +1195,7 @@
}
/**
- * @param[in] string $multilineText is one or more PHP_EOL delimited
lines to be escaped and rendered as an HTML error.
+ * @param string $multilineText is one or more PHP_EOL delimited lines
to be escaped and rendered as an HTML error.
* @see escapeHTML()
* @return string HTML escaped and rendered as an error.
* @author Keith Welter
@@ -1168,7 +1212,7 @@
* Escape the input text for HTML rendering (wrapper for
htmlspecialchars).
* @see
http://www.mediawiki.org/wiki/Cross-site_scripting#Stopping_Cross-site_scripting
* @return string escaped HTML.
- * @param[in] string $text is the text to be escaped.
+ * @param string $text is the text to be escaped.
* @author Keith Welter
*/
static function escapeHTML( $text ) {
@@ -1192,7 +1236,7 @@
}
/**
- * @param[in] $subdir is the path of a subdirectory relative to
$wgUploadDirectory.
+ * @param string $subdir is the path of a subdirectory relative to
$wgUploadDirectory.
* If the subdirectory does not exist, it is created with the same
permissions as $wgUploadDirectory.
* @return string path of a subdirectory of the wiki upload directory
($wgUploadDirectory) or false upon failure.
* @author Keith Welter
diff --git a/includes/UploadFromLocalFile.php b/includes/UploadFromLocalFile.php
index c40062e..ada99d4 100644
--- a/includes/UploadFromLocalFile.php
+++ b/includes/UploadFromLocalFile.php
@@ -18,6 +18,7 @@
/**
* This function is a no-op because a WebRequest is not used.
* It exists here because it is abstract in UploadBase.
+ * @param WebRequest &$request
*/
function initializeFromRequest( &$request ) {
}
diff --git a/includes/UploadLocalFile.php b/includes/UploadLocalFile.php
index 847c1de..de45290 100644
--- a/includes/UploadLocalFile.php
+++ b/includes/UploadLocalFile.php
@@ -56,8 +56,8 @@
* Check if uploading is allowed for the given user.
* Based on SpecialUpload::execute.
*
- * @param[in] User $user is the user to check.
- * @param[out] string $errorText is populated with an error message if
the user is not allowed to upload.
+ * @param User $user is the user to check.
+ * @param string &$errorText is populated with an error message if the
user is not allowed to upload.
* @return bool true if the user is allowed to upload, false if not.
*/
static function isUploadAllowedForUser( $user, &$errorText ) {
@@ -97,13 +97,13 @@
* Check if the upload is allowed for the given user and destination
name.
* Based on SpecialUpload::processUpload.
*
- * @param[in] UploadFromLocalFile $upload
- * @param[in] User $user is the user to check.
- * @param[in] string $desiredDestName the desired destination name of
the file to be uploaded.
- * @param[in] string $localPath the local path of the file to be
uploaded.
- * @param[in] bool $removeLocalFile remove the local file?
- * @param[in] Language $langauge to use for
- * @param[out] string $errorText is populated with an error message if
the user is not allowed to upload.
+ * @param UploadFromLocalFile $upload
+ * @param User $user is the user to check.
+ * @param string $desiredDestName the desired destination name of the
file to be uploaded.
+ * @param string $localPath the local path of the file to be uploaded.
+ * @param bool $removeLocalFile remove the local file?
+ * @param Language $language to use for
+ * @param string &$errorText is populated with an error message if the
user is not allowed to upload.
* @return bool true if the user is allowed to upload, false if not.
*/
static function isUploadAllowedForTitle( $upload, $user,
$desiredDestName, $localPath, $removeLocalFile, $language, &$errorText ) {
@@ -135,9 +135,9 @@
* Provides output to the user for an error result from
UploadBase::verifyUpload
* Based on SpecialUpload::processVerificationError.
*
- * @param[in] array $details result of UploadBase::verifyUpload
- * @param[in] Language $language for adding comma-separated lists to
some messages.
- * @param[in] string $filename is the name of the file for which upload
verification failed.
+ * @param array $details result of UploadBase::verifyUpload
+ * @param Language $language for adding comma-separated lists to some
messages.
+ * @param string $filename is the name of the file for which upload
verification failed.
* @return string error message.
* @throws MWException
*/
@@ -194,8 +194,8 @@
/**
* Based on SpecialUpload::showUploadError.
*
- * @param[in] string $message message to be included in the result
- * @param[in] string $filename is the name of the file for which upload
verification failed.
+ * @param string $message message to be included in the result
+ * @param string $filename is the name of the file for which upload
verification failed.
* @return string upload error message.
*/
static function getUploadErrorMessage( $message, $filename ) {
@@ -204,7 +204,7 @@
/**
* Given an i18n message name and arguments, return the message text.
- * @param[in] string $messageName is the name of a message in the i18n
file.
+ * @param string $messageName is the name of a message in the i18n file.
* A variable number of message arguments is supported.
* @return string error message for $messageName.
* @author Keith Welter
@@ -221,7 +221,7 @@
/**
* Check if the given file has been uploaded to the wiki.
*
- * @param[in] string $filename is the name of the file to check.
+ * @param string $fileName is the name of the file to check.
* @return File file, or null on failure
*/
static function getUploadedFile( $fileName ) {
@@ -237,6 +237,7 @@
*
* @param Title $title
* @param FileRepo $repo
+ * @param null $unused
*
* @return UploadLocalFile
*/
@@ -248,10 +249,10 @@
* Upload a file from the given local path to the given destination
name.
* Based on SpecialUpload::processUpload
*
- * @param[in] UploadFromLocalFile $upload
- * @param[in] string $desiredDestName the desired destination name of
the file to be uploaded.
- * @param[in] string $localPath the local path of the file to be
uploaded.
- * @param[in] bool $removeLocalFile remove the local file?
+ * @param UploadFromLocalFile $upload
+ * @param string $desiredDestName the desired destination name of the
file to be uploaded.
+ * @param string $localPath the local path of the file to be uploaded.
+ * @param bool $removeLocalFile remove the local file?
*
* @return bool true if the upload succeeds, false if it fails.
*/
--
To view, visit https://gerrit.wikimedia.org/r/402651
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: merged
Gerrit-Change-Id: I3ff96ec363776a12be0cc5247b3de74d172c6bd9
Gerrit-PatchSet: 3
Gerrit-Project: mediawiki/extensions/GraphViz
Gerrit-Branch: master
Gerrit-Owner: Umherirrender <[email protected]>
Gerrit-Reviewer: Samwilson <[email protected]>
Gerrit-Reviewer: Umherirrender <[email protected]>
Gerrit-Reviewer: Welterkj <[email protected]>
Gerrit-Reviewer: jenkins-bot <>
_______________________________________________
MediaWiki-commits mailing list
[email protected]
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
