jenkins-bot has submitted this change and it was merged. (
https://gerrit.wikimedia.org/r/379214 )
Change subject: Extract SummaryDescription interface
......................................................................
Extract SummaryDescription interface
Code related to formatting doesn't care about half of the methods on
the Summary class, so here is the interface describing what is really
important.
Change-Id: Ifb13e562ad8cd74a60f66f18f453f72b899ef4c2
---
A lib/includes/FormatableSummary.php
M lib/includes/Summary.php
M repo/includes/Api/EntitySavingHelper.php
M repo/includes/Interactors/ItemMergeInteractor.php
M repo/includes/Interactors/RedirectCreationInteractor.php
M repo/includes/Specials/SpecialWikibaseRepoPage.php
M repo/includes/SummaryFormatter.php
M repo/includes/UpdateRepo/UpdateRepoJob.php
8 files changed, 121 insertions(+), 22 deletions(-)
Approvals:
Aleksey Bekh-Ivanov (WMDE): Looks good to me, approved
jenkins-bot: Verified
Thiemo Mättig (WMDE): Looks good to me, but someone else must approve
diff --git a/lib/includes/FormatableSummary.php
b/lib/includes/FormatableSummary.php
new file mode 100644
index 0000000..f242ca9
--- /dev/null
+++ b/lib/includes/FormatableSummary.php
@@ -0,0 +1,96 @@
+<?php
+
+namespace Wikibase\Lib;
+
+/**
+ * Interface for consumers (typically a formatter) of auto-generated edit
summary lines that
+ * describe edits made on Wikibase entities. Wikibase edits are usually
atomic, e.g. a single label
+ * in a single language was added. The auto-summary describing this edit uses
the message
+ * "wikibase-entity-summary-wbsetlabel-add", and mentions the new label as
well as it's language
+ * code.
+ *
+ * @license GPL-2.0+
+ * @author Aleksey Bekh-Ivanov
+ * @author Thiemo Mättig
+ */
+interface FormatableSummary {
+
+ /**
+ * Returns a fragment of a message key, missing the
"wikibase-…-summary-" prefix. When displayed
+ * to the user, the message key will be prefixed with either
"wikibase-<entity type>-summary-",
+ * or with "wikibase-entity-summary-" if no message specific to the
entity type exists.
+ *
+ * Parameters of the message will be:
+ * - $1: Number of auto-summary arguments (@see getAutoSummaryArgs ) to
be used for
+ * {{PLURAL:$1|…|…}} support in the message. Note that the
auto-summary arguments themselve
+ * are not passed as parameters to the message, but appended.
+ * - $2: Language code of the edited content, or empty if not applicable
+ * (@see getLanguageCode ).
+ * - $3 to $n: Comment arguments, if present (@see getCommentArgs ).
+ *
+ * @return string
+ */
+ public function getMessageKey();
+
+ /**
+ * The language of the content that was edited, e.g. when the summary
represents an edit of a
+ * label, description, or set of aliases in a specific language. Not
set if not applicable.
+ *
+ * Will be used as argument $2 in the message.
+ *
+ * @return string|null
+ */
+ public function getLanguageCode();
+
+ /**
+ * Comment arguments will be used as parameters for the message. The
element with index 0 in the
+ * array will become $3 in the message, and so on.
+ *
+ * Elements in the array that are not strings will be forcefully
converted to strings, utilizing
+ * proper formatters.
+ *
+ * @note Duplicate values in the comment as well as auto-summary
arguments are not a mistake. If
+ * duplication makes sense depends on the edit, and how the message and
the appended
+ * auto-summary can represent the edit.
+ *
+ * @return array
+ */
+ public function getCommentArgs();
+
+ /**
+ * An array or associative array of values to describe the new revision
this summary represents,
+ * for example:
+ * - The actual label, description, or set of aliases that was set in
an edit.
+ * - A formatted property ID => value pair.
+ * - The site IDs and titles of two pages that have been merged via the
"wblinktitles" module.
+ *
+ * The auto-summary arguments are compiled to a string and form a
plain, unlocalized,
+ * automatically generated summary that is appended to the message.
+ *
+ * A numerically indexed array will be displayed as a comma separated
list of values, e.g.
+ * "a, b". An associative array will be displayed as a comma separated
list of values prefixed
+ * with keys, e.g. "en: en-label, fr: fr-label".
+ *
+ * Elements in the array that are not strings will be forcefully
converted to strings, utilizing
+ * proper formatters.
+ *
+ * @note Duplicate values in the comment as well as auto-summary
arguments are not a mistake. If
+ * duplication makes sense depends on the edit, and how the message and
the appended
+ * auto-summary can represent the edit.
+ *
+ * @return array
+ */
+ public function getAutoSummaryArgs();
+
+ /**
+ * The user-provided edit summary, or null if none was given. Typically
provided via the API.
+ *
+ * If both a user-provided summary as well as auto-summary arguments
are provided
+ * (@see getAutoSummaryArgs ), the user's comment will be appended to
the auto-summary,
+ * separated by a comma.
+ *
+ * @return string|null
+ */
+ public function getUserSummary();
+
+}
diff --git a/lib/includes/Summary.php b/lib/includes/Summary.php
index e75f5ad..bcd154b 100644
--- a/lib/includes/Summary.php
+++ b/lib/includes/Summary.php
@@ -2,6 +2,8 @@
namespace Wikibase;
+use Wikibase\Lib\FormatableSummary;
+
/**
* A Summary object can be used to build complex, translatable summaries.
*
@@ -10,7 +12,7 @@
* @author Daniel Kinzler
* @author Tobias Gritschacher < tobias.gritschac...@wikimedia.de >
*/
-class Summary {
+class Summary implements FormatableSummary {
/**
* @var string|null
@@ -38,7 +40,7 @@
private $summaryArgs;
/**
- * @var string
+ * @var string|null The user-provided edit summary, or null if none was
given.
*/
private $userSummary;
@@ -64,9 +66,7 @@
}
/**
- * Set the user provided edit summary
- *
- * @param string|null $summary edit summary provided by the user
+ * @param string|null $summary The user-provided edit summary, or null
if none was given.
*/
public function setUserSummary( $summary = null ) {
$this->userSummary = $summary === null ? null :
(string)$summary;
diff --git a/repo/includes/Api/EntitySavingHelper.php
b/repo/includes/Api/EntitySavingHelper.php
index eeca24c..1857032 100644
--- a/repo/includes/Api/EntitySavingHelper.php
+++ b/repo/includes/Api/EntitySavingHelper.php
@@ -17,7 +17,7 @@
use Wikibase\Lib\Store\EntityRevisionLookup;
use Wikibase\Lib\Store\EntityStore;
use Wikibase\Lib\Store\StorageException;
-use Wikibase\Summary;
+use Wikibase\Lib\FormatableSummary;
use Wikibase\SummaryFormatter;
/**
@@ -296,7 +296,7 @@
* handleStatus()).
*
* @param EntityDocument $entity The entity to save
- * @param string|Summary $summary The edit summary
+ * @param string|FormatableSummary $summary The edit summary
* @param int $flags The edit flags (see WikiPage::doEditContent)
*
* @throws LogicException if not in write mode
@@ -319,7 +319,7 @@
);
}
- if ( $summary instanceof Summary ) {
+ if ( $summary instanceof FormatableSummary ) {
$summary = $this->summaryFormatter->formatSummary(
$summary );
}
diff --git a/repo/includes/Interactors/ItemMergeInteractor.php
b/repo/includes/Interactors/ItemMergeInteractor.php
index a712427..686943c 100644
--- a/repo/includes/Interactors/ItemMergeInteractor.php
+++ b/repo/includes/Interactors/ItemMergeInteractor.php
@@ -19,6 +19,7 @@
use Wikibase\Lib\Store\StorageException;
use Wikibase\Repo\Store\EntityPermissionChecker;
use Wikibase\Summary;
+use Wikibase\Lib\FormatableSummary;
use Wikibase\SummaryFormatter;
/**
@@ -264,7 +265,7 @@
return [ $fromRev, $toRev ];
}
- private function saveItem( Item $item, Summary $summary, $bot ) {
+ private function saveItem( Item $item, FormatableSummary $summary, $bot
) {
// Given we already check all constraints in ChangeOpsMerge,
it's
// fine to ignore them here. This is also needed to not run into
// the constraints we're supposed to ignore (see
ChangeOpsMerge::removeConflictsWithEntity
diff --git a/repo/includes/Interactors/RedirectCreationInteractor.php
b/repo/includes/Interactors/RedirectCreationInteractor.php
index 4cf97ec..73170e2 100644
--- a/repo/includes/Interactors/RedirectCreationInteractor.php
+++ b/repo/includes/Interactors/RedirectCreationInteractor.php
@@ -15,6 +15,7 @@
use Wikibase\Repo\Hooks\EditFilterHookRunner;
use Wikibase\Repo\Store\EntityPermissionChecker;
use Wikibase\Summary;
+use Wikibase\Lib\FormatableSummary;
use Wikibase\SummaryFormatter;
/**
@@ -219,12 +220,12 @@
/**
* @param EntityRedirect $redirect
- * @param Summary $summary
+ * @param FormatableSummary $summary
* @param bool $bot Whether the edit should be marked as bot
*
* @throws RedirectCreationException
*/
- private function saveRedirect( EntityRedirect $redirect, Summary
$summary, $bot ) {
+ private function saveRedirect( EntityRedirect $redirect,
FormatableSummary $summary, $bot ) {
$summary = $this->summaryFormatter->formatSummary( $summary );
$flags = 0;
if ( $bot ) {
diff --git a/repo/includes/Specials/SpecialWikibaseRepoPage.php
b/repo/includes/Specials/SpecialWikibaseRepoPage.php
index 87493c3..1f3ff50 100644
--- a/repo/includes/Specials/SpecialWikibaseRepoPage.php
+++ b/repo/includes/Specials/SpecialWikibaseRepoPage.php
@@ -14,7 +14,7 @@
use Wikibase\Lib\Store\EntityTitleLookup;
use Wikibase\Lib\UserInputException;
use Wikibase\Repo\WikibaseRepo;
-use Wikibase\Summary;
+use Wikibase\Lib\FormatableSummary;
use Wikibase\SummaryFormatter;
/**
@@ -166,7 +166,7 @@
* @note Call prepareEditEntity() first.
*
* @param EntityDocument $entity
- * @param Summary $summary
+ * @param FormatableSummary $summary
* @param string $token
* @param int $flags The edit flags (see WikiPage::doEditContent)
*
@@ -174,7 +174,7 @@
*/
protected function saveEntity(
EntityDocument $entity,
- Summary $summary,
+ FormatableSummary $summary,
$token,
$flags = EDIT_UPDATE
) {
diff --git a/repo/includes/SummaryFormatter.php
b/repo/includes/SummaryFormatter.php
index 411e909..1cc951b 100644
--- a/repo/includes/SummaryFormatter.php
+++ b/repo/includes/SummaryFormatter.php
@@ -14,6 +14,7 @@
use Wikibase\DataModel\Entity\EntityIdParsingException;
use Wikibase\DataModel\Snak\Snak;
use Wikibase\Lib\SnakFormatter;
+use Wikibase\Lib\FormatableSummary;
/**
* Formatter for Summary objects
@@ -90,11 +91,11 @@
* and the second one is always the language code supplied via
setLanguage()
* (or the constructor).
*
- * @param Summary $summary
+ * @param FormatableSummary $summary
*
* @return string with a formatted comment, or possibly an empty string
*/
- public function formatAutoComment( Summary $summary ) {
+ public function formatAutoComment( FormatableSummary $summary ) {
$composite = $summary->getMessageKey();
$summaryArgCount = count( $summary->getAutoSummaryArgs() );
@@ -117,12 +118,12 @@
/**
* Formats the auto summary part of a full summary.
*
- * @param Summary $summary
+ * @param FormatableSummary $summary
*
* @throws MWException
* @return string The auto summary arguments comma-separated
*/
- public function formatAutoSummary( Summary $summary ) {
+ public function formatAutoSummary( FormatableSummary $summary ) {
$summaryArgs = $summary->getAutoSummaryArgs();
$parts = $this->formatArgList( $summaryArgs );
@@ -265,11 +266,11 @@
/**
* Format the given summary
*
- * @param Summary $summary
+ * @param FormatableSummary $summary
*
* @return string to be used for the summary
*/
- public function formatSummary( Summary $summary ) {
+ public function formatSummary( FormatableSummary $summary ) {
$userSummary = $summary->getUserSummary();
return $this->assembleSummaryString(
diff --git a/repo/includes/UpdateRepo/UpdateRepoJob.php
b/repo/includes/UpdateRepo/UpdateRepoJob.php
index 1924148..78d58bf 100644
--- a/repo/includes/UpdateRepo/UpdateRepoJob.php
+++ b/repo/includes/UpdateRepo/UpdateRepoJob.php
@@ -13,7 +13,7 @@
use Wikibase\Lib\Store\EntityStore;
use Wikibase\Lib\Store\StorageException;
use Wikibase\Repo\WikibaseRepo;
-use Wikibase\Summary;
+use Wikibase\Lib\FormatableSummary;
use Wikibase\SummaryFormatter;
/**
@@ -78,7 +78,7 @@
/**
* Get a Summary object for the edit
*
- * @return Summary
+ * @return FormatableSummary
*/
abstract public function getSummary();
--
To view, visit https://gerrit.wikimedia.org/r/379214
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: merged
Gerrit-Change-Id: Ifb13e562ad8cd74a60f66f18f453f72b899ef4c2
Gerrit-PatchSet: 3
Gerrit-Project: mediawiki/extensions/Wikibase
Gerrit-Branch: master
Gerrit-Owner: Aleksey Bekh-Ivanov (WMDE) <aleksey.bekh-iva...@wikimedia.de>
Gerrit-Reviewer: Addshore <addshorew...@gmail.com>
Gerrit-Reviewer: Aleksey Bekh-Ivanov (WMDE) <aleksey.bekh-iva...@wikimedia.de>
Gerrit-Reviewer: Hoo man <h...@online.de>
Gerrit-Reviewer: Jakob <jakob.warkot...@wikimedia.de>
Gerrit-Reviewer: Jonas Kress (WMDE) <jonas.kr...@wikimedia.de>
Gerrit-Reviewer: Ladsgroup <ladsgr...@gmail.com>
Gerrit-Reviewer: Thiemo Mättig (WMDE) <thiemo.maet...@wikimedia.de>
Gerrit-Reviewer: WMDE-leszek <leszek.mani...@wikimedia.de>
Gerrit-Reviewer: jenkins-bot <>
_______________________________________________
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
