Addshore has submitted this change and it was merged.
Change subject: Doxygen comments updated in Summary related classes
......................................................................
Doxygen comments updated in Summary related classes
* Applied good practice to variable args functions (according to
the Doxygen and phpDocumentor documentations).
* Fixed types, e.g. object[] for arrays the usually contain strings.
* Break long lines.
* Descriptions start uppercase (easier to read, even if it's not a
full sentence).
Change-Id: I3b35d1d7313d6f0e1b8e763bd03c0e8c21038c3f
---
M lib/includes/Summary.php
M repo/includes/ClaimSummaryBuilder.php
M repo/includes/SummaryFormatter.php
3 files changed, 39 insertions(+), 29 deletions(-)
Approvals:
WikidataJenkins: Verified
Addshore: Looks good to me, approved
diff --git a/lib/includes/Summary.php b/lib/includes/Summary.php
index f587fa0..3f68204 100644
--- a/lib/includes/Summary.php
+++ b/lib/includes/Summary.php
@@ -48,7 +48,7 @@
protected $userSummary;
/**
- * indicates a specific type of formatting
+ * Indicates a specific type of formatting
*/
const USE_COMMENT = 2;
const USE_SUMMARY = 4;
@@ -59,11 +59,11 @@
*
* @since 0.4
*
- * @param string $moduleName the module part of the autocomment
- * @param string $actionName the action part of the autocomment
- * @param string $language the language to use as the second
autocomment argument
- * @param object[] $commentArgs the arguments to the autocomment
- * @param object[] $summaryArgs the arguments to the autosummary
+ * @param string $moduleName The module part of the auto comment
+ * @param string $actionName The action part of the auto comment
+ * @param string $language The language to use as the second auto
comment argument
+ * @param array $commentArgs The arguments to the auto comment
+ * @param array $summaryArgs The arguments to the auto summary
*/
public function __construct( $moduleName = null, $actionName = null,
$language = null,
$commentArgs = array(), $summaryArgs = array()
@@ -181,11 +181,11 @@
}
/**
- * Add autocomment arguments.
+ * Add auto comment arguments.
*
* @since 0.4
*
- * @param array|strings... parts to be stringed together
+ * @param mixed [$args,...] Parts to be stringed together
*/
public function addAutoCommentArgs( /*...*/ ) {
$args = func_get_args();
@@ -197,13 +197,12 @@
$this->commentArgs = array_merge( $this->commentArgs, $args );
}
-
/**
- * Add to the summary part
+ * Add arguments to the summary part.
*
* @since 0.4
*
- * @param array|strings... parts to be stringed together
+ * @param mixed [$args,...] Parts to be stringed together
*/
public function addAutoSummaryArgs( /*...*/ ) {
$args = func_get_args();
@@ -216,21 +215,21 @@
}
/**
- * @return object[]
+ * @return array
*/
public function getCommentArgs() {
return $this->commentArgs;
}
/**
- * @return object[]
+ * @return array
*/
public function getAutoSummaryArgs() {
return $this->summaryArgs;
}
/**
- * @deprecated use SummaryFormatter instead
+ * @deprecated Use SummaryFormatter instead
* @throws LogicException
*/
public function toString() {
diff --git a/repo/includes/ClaimSummaryBuilder.php
b/repo/includes/ClaimSummaryBuilder.php
index 07da8eb..5e98795 100644
--- a/repo/includes/ClaimSummaryBuilder.php
+++ b/repo/includes/ClaimSummaryBuilder.php
@@ -98,12 +98,13 @@
}
/**
- * Build key (property) => value pairs for summary arguments
+ * Builds an associative array that can be used as summary arguments.
It uses property IDs as
+ * array keys and builds arrays of the main Snaks of all Claims given
by the GUIDs.
*
* @param Claims $claims
* @param string[] $guids
*
- * @return mixed[] // propertyId (prefixed) => array of values
+ * @return array[] Associative array that contains property ID => array
of main Snaks
*/
protected function buildSummaryArgs( Claims $claims, array $guids ) {
$pairs = array();
@@ -121,6 +122,7 @@
}
}
- return ( array( $pairs ) );
+ return array( $pairs );
}
+
}
diff --git a/repo/includes/SummaryFormatter.php
b/repo/includes/SummaryFormatter.php
index ced104c..6bd3c6c 100644
--- a/repo/includes/SummaryFormatter.php
+++ b/repo/includes/SummaryFormatter.php
@@ -49,11 +49,13 @@
* @param EntityIdFormatter $idFormatter
* @param ValueFormatter $valueFormatter
* @param SnakFormatter $snakFormatter
- * @param \Language $language
+ * @param Language $language
*
- * @throws \InvalidArgumentException
+ * @throws InvalidArgumentException
*/
- public function __construct( EntityIdFormatter $idFormatter,
ValueFormatter $valueFormatter, SnakFormatter $snakFormatter, Language
$language ) {
+ public function __construct( EntityIdFormatter $idFormatter,
ValueFormatter $valueFormatter,
+ SnakFormatter $snakFormatter, Language $language
+ ) {
if ( $snakFormatter->getFormat() !==
SnakFormatter::FORMAT_PLAIN ) {
throw new InvalidArgumentException(
'Expected $snakFormatter to procude text/plain
output, not '
@@ -77,6 +79,7 @@
* @since 0.5
*
* @param Summary $summary
+ *
* @return string with a formatted comment, or possibly an empty string
*/
public function formatAutoComment( Summary $summary ) {
@@ -100,7 +103,7 @@
}
/**
- * Format the autosummary part of a full summary
+ * Formats the auto summary part of a full summary.
*
* @since 0.4
*
@@ -108,7 +111,7 @@
*
* @throws \MWException
*
- * @return string The $parts concatenated
+ * @return string The auto summary arguments comma-separated
*/
public function formatAutoSummary( Summary $summary ) {
$summaryArgs = $summary->getAutoSummaryArgs();
@@ -131,7 +134,7 @@
}
/**
- * @param mixed[] $args
+ * @param array $args
*
* @return string[]
*/
@@ -151,7 +154,7 @@
}
/**
- * Format an autosummary argument
+ * Format an auto summary argument
*
* @since 0.4
*
@@ -255,12 +258,16 @@
* @since 0.5
*
* @param Summary $summary
- * @param int $length max length of the summary
- * @param int $format bitset indicating what to include, see the
USE_XXX constants.
+ * @param int $length Max length of the summary
+ * @param int $format Bit field indicating what to include, see the
Summary::USE_XXX constants.
*
* @return string to be used for the summary
+ *
+ * @see Summary::USE_ALL
*/
- public function formatSummary( Summary $summary, $length =
SUMMARY_MAX_LENGTH, $format = Summary::USE_ALL ) {
+ public function formatSummary( Summary $summary, $length =
SUMMARY_MAX_LENGTH,
+ $format = Summary::USE_ALL
+ ) {
$userSummary = $summary->getUserSummary();
if ( !is_null( $userSummary ) ) {
@@ -271,8 +278,10 @@
$autoComment = $this->formatAutoComment( $summary );
- $autoComment = ( $format & Summary::USE_COMMENT ) ?
$this->stringNormalizer->trimToNFC( $autoComment ) : '';
- $autoSummary = ( $format & Summary::USE_SUMMARY ) ?
$this->stringNormalizer->trimToNFC( $autoSummary ) : '';
+ $autoComment = ( $format & Summary::USE_COMMENT )
+ ? $this->stringNormalizer->trimToNFC( $autoComment ) :
'';
+ $autoSummary = ( $format & Summary::USE_SUMMARY )
+ ? $this->stringNormalizer->trimToNFC( $autoSummary ) :
'';
$totalSummary = self::assembleSummaryString( $autoComment,
$autoSummary, $length );
return $totalSummary;
--
To view, visit https://gerrit.wikimedia.org/r/117227
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: merged
Gerrit-Change-Id: I3b35d1d7313d6f0e1b8e763bd03c0e8c21038c3f
Gerrit-PatchSet: 1
Gerrit-Project: mediawiki/extensions/Wikibase
Gerrit-Branch: master
Gerrit-Owner: Thiemo Mättig (WMDE) <thiemo.maet...@wikimedia.de>
Gerrit-Reviewer: Addshore <addshorew...@gmail.com>
Gerrit-Reviewer: Aude <aude.w...@gmail.com>
Gerrit-Reviewer: Daniel Kinzler <daniel.kinz...@wikimedia.de>
Gerrit-Reviewer: Tobias Gritschacher <tobias.gritschac...@wikimedia.de>
Gerrit-Reviewer: WikidataJenkins <wikidata-servi...@wikimedia.de>
Gerrit-Reviewer: jenkins-bot <>
_______________________________________________
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
