Thiemo Mättig (WMDE) has uploaded a new change for review.
https://gerrit.wikimedia.org/r/261361
Change subject: Cleanup ValueFormatter:format documentation tags
......................................................................
Cleanup ValueFormatter:format documentation tags
This patch exclusively touches documentation and should be easy to
review, even if it contains a lot of files.
I'm removing some lines that are either copy pasted by mistake or do
not add any helpful information (e.g. "formatSnak formats a snak").
Change-Id: I50711f1cb587fc1b779ccadc85c06a1cf0cf18d0
---
M client/includes/Usage/UsageTrackingSnakFormatter.php
M lib/includes/formatters/CommonsLinkFormatter.php
M lib/includes/formatters/DispatchingSnakFormatter.php
M lib/includes/formatters/ErrorHandlingSnakFormatter.php
M lib/includes/formatters/EscapingSnakFormatter.php
M lib/includes/formatters/GlobeCoordinateDetailsFormatter.php
M lib/includes/formatters/HtmlExternalIdentifierFormatter.php
M lib/includes/formatters/HtmlTimeFormatter.php
M lib/includes/formatters/HtmlUrlFormatter.php
M lib/includes/formatters/PropertyValueSnakFormatter.php
M lib/includes/formatters/QuantityDetailsFormatter.php
M lib/includes/formatters/SnakFormatter.php
M lib/includes/formatters/TimeDetailsFormatter.php
M lib/includes/formatters/UnDeserializableValueFormatter.php
M lib/includes/formatters/VocabularyUriFormatter.php
M lib/includes/formatters/WikitextExternalIdentifierFormatter.php
M repo/includes/Localizer/MessageParameterFormatter.php
17 files changed, 56 insertions(+), 51 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/mediawiki/extensions/Wikibase
refs/changes/61/261361/1
diff --git a/client/includes/Usage/UsageTrackingSnakFormatter.php
b/client/includes/Usage/UsageTrackingSnakFormatter.php
index bdc0afc..f5eda70 100644
--- a/client/includes/Usage/UsageTrackingSnakFormatter.php
+++ b/client/includes/Usage/UsageTrackingSnakFormatter.php
@@ -47,11 +47,11 @@
}
/**
- * Formats a snak.
+ * @see SnakFormatter::formatSnak
*
* @param Snak $snak
*
- * @return string
+ * @return string Either plain text, wikitext or HTML, depending on the
$snakFormatter provided.
*/
public function formatSnak( Snak $snak ) {
if ( $snak instanceof PropertyValueSnak ) {
@@ -80,12 +80,7 @@
* Returns the format ID of the format this formatter generates.
* This uses the FORMAT_XXX constants defined in
OutputFormatSnakFormatterFactory.
*
- * @see SnakFormatter::FORMAT_PLAIN
- * @see SnakFormatter::FORMAT_WIKI
- * @see SnakFormatter::FORMAT_HTML
- * @see SnakFormatter::FORMAT_HTML_WIDGET
- *
- * @return string
+ * @return string One of the SnakFormatter::FORMAT_... constants.
*/
public function getFormat() {
return $this->snakFormatter->getFormat();
diff --git a/lib/includes/formatters/CommonsLinkFormatter.php
b/lib/includes/formatters/CommonsLinkFormatter.php
index 0b9fc6b..5af7196 100644
--- a/lib/includes/formatters/CommonsLinkFormatter.php
+++ b/lib/includes/formatters/CommonsLinkFormatter.php
@@ -10,7 +10,8 @@
use ValueFormatters\ValueFormatter;
/**
- * Formats a StringValue as an HTML link.
+ * Formats the StringValue from a "commonsMedia" snak as an HTML link pointing
to the file
+ * description page on Wikimedia Commons.
*
* @since 0.5
*
diff --git a/lib/includes/formatters/DispatchingSnakFormatter.php
b/lib/includes/formatters/DispatchingSnakFormatter.php
index fd7467f..9e27d59 100644
--- a/lib/includes/formatters/DispatchingSnakFormatter.php
+++ b/lib/includes/formatters/DispatchingSnakFormatter.php
@@ -19,7 +19,7 @@
class DispatchingSnakFormatter implements SnakFormatter {
/**
- * @var string
+ * @var string One of the SnakFormatter::FORMAT_... constants.
*/
private $format;
@@ -73,6 +73,12 @@
$this->formattersByDataType = $formattersByDataType;
}
+ /**
+ * @param string $format MIME type
+ * @param SnakFormatter[] $formatters
+ *
+ * @throws InvalidArgumentException
+ */
private function assertFormatterArray( $format, array $formatters ) {
foreach ( $formatters as $type => $formatter ) {
if ( !is_string( $type ) ) {
@@ -114,6 +120,8 @@
}
/**
+ * @see SnakFormatter::formatSnak
+ *
* Formats the given Snak by finding an appropriate formatter among the
ones supplied
* to the constructor, and applying it.
*
@@ -149,7 +157,7 @@
/**
* @see SnakFormatter::getFormat
*
- * @return string
+ * @return string One of the SnakFormatter::FORMAT_... constants.
*/
public function getFormat() {
return $this->format;
diff --git a/lib/includes/formatters/ErrorHandlingSnakFormatter.php
b/lib/includes/formatters/ErrorHandlingSnakFormatter.php
index 507dbcc..a9d5b5a 100644
--- a/lib/includes/formatters/ErrorHandlingSnakFormatter.php
+++ b/lib/includes/formatters/ErrorHandlingSnakFormatter.php
@@ -55,14 +55,13 @@
}
/**
- * Formats the given Snak by looking up its property type and calling
the
- * SnakValueFormatter supplied to the constructor.
+ * @see SnakFormatter::formatSnak
*
* @param Snak $snak
*
* @throws InvalidArgumentException
* @throws FormattingException
- * @return string Text in the format indicated by getFormat()
+ * @return string Either plain text, wikitext or HTML, depending on the
$snakFormatter provided.
*/
public function formatSnak( Snak $snak ) {
try {
@@ -138,7 +137,7 @@
/**
* @see SnakFormatter::getFormat
*
- * @return string
+ * @return string One of the SnakFormatter::FORMAT_... constants.
*/
public function getFormat() {
return $this->snakFormatter->getFormat();
diff --git a/lib/includes/formatters/EscapingSnakFormatter.php
b/lib/includes/formatters/EscapingSnakFormatter.php
index 926746c..69566a5 100644
--- a/lib/includes/formatters/EscapingSnakFormatter.php
+++ b/lib/includes/formatters/EscapingSnakFormatter.php
@@ -25,12 +25,12 @@
private $escapeCallback;
/**
- * @var string
+ * @var string One of the SnakFormatter::FORMAT_... constants.
*/
private $format;
/**
- * @param string $format
+ * @param string $format One of the SnakFormatter::FORMAT_... constants.
* @param SnakFormatter $formatter
* @param callable $escapeCallback A callable taking plain text and
returning escaped text.
*/
@@ -48,7 +48,7 @@
*
* @param Snak $snak
*
- * @return string
+ * @return string Either wikitext or HTML, depending on the
$escapeCallback provided.
*/
public function formatSnak( Snak $snak ) {
$text = $this->formatter->formatSnak( $snak );
@@ -59,7 +59,7 @@
/**
* @see SnakFormatter::getFormat
*
- * @return string
+ * @return string One of the SnakFormatter::FORMAT_... constants.
*/
public function getFormat() {
return $this->format;
diff --git a/lib/includes/formatters/GlobeCoordinateDetailsFormatter.php
b/lib/includes/formatters/GlobeCoordinateDetailsFormatter.php
index ca2c28d..b88cb30 100644
--- a/lib/includes/formatters/GlobeCoordinateDetailsFormatter.php
+++ b/lib/includes/formatters/GlobeCoordinateDetailsFormatter.php
@@ -40,10 +40,10 @@
}
/**
+ * @see ValueFormatter::format
+ *
* Generates HTML representing the details of a GlobeCoordinateValue,
* as an itemized list.
- *
- * @since 0.5
*
* @param GlobeCoordinateValue $value
*
diff --git a/lib/includes/formatters/HtmlExternalIdentifierFormatter.php
b/lib/includes/formatters/HtmlExternalIdentifierFormatter.php
index d4e1370..1591502 100644
--- a/lib/includes/formatters/HtmlExternalIdentifierFormatter.php
+++ b/lib/includes/formatters/HtmlExternalIdentifierFormatter.php
@@ -34,6 +34,8 @@
}
/**
+ * @see SnakFormatter::format
+ *
* Formats the given Snak's value as a HTML link.
* The URL of that link is determined using a SnakUrlExpander.
* If the snak could not be expanded into a URL, the identifier is
returned as simple text.
diff --git a/lib/includes/formatters/HtmlTimeFormatter.php
b/lib/includes/formatters/HtmlTimeFormatter.php
index 2f498fa..abad638 100644
--- a/lib/includes/formatters/HtmlTimeFormatter.php
+++ b/lib/includes/formatters/HtmlTimeFormatter.php
@@ -53,8 +53,6 @@
/**
* @see ValueFormatter::format
*
- * @since 0.5
- *
* @param TimeValue $value
*
* @throws InvalidArgumentException
diff --git a/lib/includes/formatters/HtmlUrlFormatter.php
b/lib/includes/formatters/HtmlUrlFormatter.php
index d561aaa..5a97960 100644
--- a/lib/includes/formatters/HtmlUrlFormatter.php
+++ b/lib/includes/formatters/HtmlUrlFormatter.php
@@ -9,7 +9,7 @@
use ValueFormatters\ValueFormatter;
/**
- * Formats a StringValue as an HTML link.
+ * Formats the StringValue from a "url" snak as an HTML link pointing to that
URL.
*
* @since 0.5
*
@@ -35,9 +35,9 @@
}
/**
- * Formats the given URL as an HTML link
+ * @see ValueFormatter::format
*
- * @since 0.5
+ * Formats the given URL as an HTML link
*
* @param StringValue $value The URL to turn into a link
*
diff --git a/lib/includes/formatters/PropertyValueSnakFormatter.php
b/lib/includes/formatters/PropertyValueSnakFormatter.php
index a00d008..8964b07 100644
--- a/lib/includes/formatters/PropertyValueSnakFormatter.php
+++ b/lib/includes/formatters/PropertyValueSnakFormatter.php
@@ -26,7 +26,7 @@
class PropertyValueSnakFormatter implements SnakFormatter {
/**
- * @var string
+ * @var string One of the SnakFormatter::FORMAT_... constants.
*/
private $format;
@@ -79,8 +79,10 @@
}
/**
+ * @see SnakFormatter::formatSnak
+ *
* Formats the given Snak by looking up its property type and calling
the
- * SnakValueFormatter supplied to the constructor.
+ * ValueFormatter supplied to the constructor.
*
* @param Snak $snak
*
@@ -88,7 +90,8 @@
* @throws InvalidArgumentException
* @throws MismatchingDataValueTypeException
* @throws FormattingException
- * @return string
+ * @return string Either plain text, wikitext or HTML, depending on the
$valueFormatter
+ * provided.
*/
public function formatSnak( Snak $snak ) {
if ( !( $snak instanceof PropertyValueSnak ) ) {
@@ -168,7 +171,8 @@
* @param string $dataTypeId
*
* @throws FormattingException
- * @return string
+ * @return string Either plain text, wikitext or HTML, depending on the
$valueFormatter
+ * provided.
*/
private function formatValue( DataValue $value, $dataTypeId = null ) {
if ( !$this->isUnDeserializableValue( $value ) ) {
@@ -187,7 +191,7 @@
/**
* @see SnakFormatter::getFormat
*
- * @return string
+ * @return string One of the SnakFormatter::FORMAT_... constants.
*/
public function getFormat() {
return $this->format;
diff --git a/lib/includes/formatters/QuantityDetailsFormatter.php
b/lib/includes/formatters/QuantityDetailsFormatter.php
index 8f54e6e..2b94a0e 100644
--- a/lib/includes/formatters/QuantityDetailsFormatter.php
+++ b/lib/includes/formatters/QuantityDetailsFormatter.php
@@ -72,10 +72,10 @@
}
/**
+ * @see ValueFormatter::format
+ *
* Generates HTML representing the details of a QuantityValue,
* as an itemized list.
- *
- * @since 0.5
*
* @param QuantityValue $value
*
diff --git a/lib/includes/formatters/SnakFormatter.php
b/lib/includes/formatters/SnakFormatter.php
index 5d69c63..f87eb8c 100644
--- a/lib/includes/formatters/SnakFormatter.php
+++ b/lib/includes/formatters/SnakFormatter.php
@@ -44,8 +44,6 @@
const ON_ERROR_FAIL = 'fail';
/**
- * Formats a snak.
- *
* @param Snak $snak
*
* @return string
@@ -56,12 +54,7 @@
* Returns the format ID of the format this formatter generates.
* This uses the FORMAT_XXX constants defined in
OutputFormatSnakFormatterFactory.
*
- * @see SnakFormatter::FORMAT_PLAIN
- * @see SnakFormatter::FORMAT_WIKI
- * @see SnakFormatter::FORMAT_HTML
- * @see SnakFormatter::FORMAT_HTML_WIDGET
- *
- * @return string
+ * @return string One of the self::FORMAT_... constants.
*/
public function getFormat();
diff --git a/lib/includes/formatters/TimeDetailsFormatter.php
b/lib/includes/formatters/TimeDetailsFormatter.php
index 5ce416c..36cd3ef 100644
--- a/lib/includes/formatters/TimeDetailsFormatter.php
+++ b/lib/includes/formatters/TimeDetailsFormatter.php
@@ -45,10 +45,10 @@
}
/**
+ * @see ValueFormatter::format
+ *
* Generates HTML representing the details of a TimeValue,
* as an itemized list.
- *
- * @since 0.5
*
* @param TimeValue $value
*
diff --git a/lib/includes/formatters/UnDeserializableValueFormatter.php
b/lib/includes/formatters/UnDeserializableValueFormatter.php
index 6cba065..041cb8d 100644
--- a/lib/includes/formatters/UnDeserializableValueFormatter.php
+++ b/lib/includes/formatters/UnDeserializableValueFormatter.php
@@ -8,7 +8,10 @@
use ValueFormatters\ValueFormatterBase;
/**
- * Formatter for UnDeserializableValue
+ * A ValueFormatter for UnDeserializableValue objects. It acts as a fallback
when neither the
+ * property type nor the value type are known. It does not show any
information from the value, but
+ * the message "The value is invalid and cannot be displayed" instead. The
message can be changed
+ * via an option.
*
* @since 0.5
*
@@ -29,13 +32,11 @@
}
/**
- * Formats an UnDeserializableValue
- *
- * @since 0.5
+ * @see ValueFormatter::format
*
* @param DataValue $dataValue Unused in this implementation.
*
- * @return string
+ * @return string Unescaped message text.
*/
public function format( $dataValue ) {
$langCode = $this->options->getOption( self::OPT_LANG );
diff --git a/lib/includes/formatters/VocabularyUriFormatter.php
b/lib/includes/formatters/VocabularyUriFormatter.php
index da61f3e..0ce9478 100644
--- a/lib/includes/formatters/VocabularyUriFormatter.php
+++ b/lib/includes/formatters/VocabularyUriFormatter.php
@@ -55,6 +55,8 @@
}
/**
+ * @see ValueFormatter::format
+ *
* @param string $conceptUri
*
* @throws InvalidArgumentException
diff --git a/lib/includes/formatters/WikitextExternalIdentifierFormatter.php
b/lib/includes/formatters/WikitextExternalIdentifierFormatter.php
index e7c1377..414cb25 100644
--- a/lib/includes/formatters/WikitextExternalIdentifierFormatter.php
+++ b/lib/includes/formatters/WikitextExternalIdentifierFormatter.php
@@ -41,6 +41,8 @@
}
/**
+ * @see SnakFormatter::format
+ *
* Formats the given Snak as an wikitext link to an authoritative
resource.
* The URL of that link is determined using a SnakUrlExpander.
* If the snak could not be expanded into a URL, the identifier is
returned as simple text.
diff --git a/repo/includes/Localizer/MessageParameterFormatter.php
b/repo/includes/Localizer/MessageParameterFormatter.php
index ae38d64..0c13ef5 100644
--- a/repo/includes/Localizer/MessageParameterFormatter.php
+++ b/repo/includes/Localizer/MessageParameterFormatter.php
@@ -17,6 +17,8 @@
* ValueFormatter for formatting objects that may be encountered in
* parameters of ValueValidators\Error objects as wikitext.
*
+ * @since 0.5
+ *
* @license GPL 2+
* @author Daniel Kinzler
*/
@@ -68,9 +70,7 @@
}
/**
- * Formats a value.
- *
- * @since 0.1
+ * @see ValueFormatter::format
*
* @param mixed $value The value to format
*
--
To view, visit https://gerrit.wikimedia.org/r/261361
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I50711f1cb587fc1b779ccadc85c06a1cf0cf18d0
Gerrit-PatchSet: 1
Gerrit-Project: mediawiki/extensions/Wikibase
Gerrit-Branch: master
Gerrit-Owner: Thiemo Mättig (WMDE) <[email protected]>
_______________________________________________
MediaWiki-commits mailing list
[email protected]
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
