Thiemo Mättig (WMDE) has uploaded a new change for review.
https://gerrit.wikimedia.org/r/260565
Change subject: More specific class level and @return docs in parsers and
formatters
......................................................................
More specific class level and @return docs in parsers and formatters
This is a start. I want to do a lot more like this, but this needs time.
I'm removing the line from RdfWriterFactory because it adds nothing
thats not already obvious from the class name. This makes the class
easier to find when looking for undocumented classes.
Change-Id: I333d0645248e07a73f8df08a7616680f7314838f
---
M lib/includes/formatters/EntityIdHtmlLinkFormatter.php
M lib/includes/formatters/EntityIdLinkFormatter.php
M lib/includes/formatters/EntityIdPlainLinkFormatter.php
M lib/includes/formatters/EntityIdTitleFormatter.php
M lib/includes/formatters/EntityIdValueFormatter.php
M lib/includes/formatters/HtmlTimeFormatter.php
M lib/includes/formatters/TimeDetailsFormatter.php
M purtle/src/RdfWriterFactory.php
M repo/includes/Parsers/YearTimeParser.php
9 files changed, 29 insertions(+), 9 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/mediawiki/extensions/Wikibase
refs/changes/65/260565/1
diff --git a/lib/includes/formatters/EntityIdHtmlLinkFormatter.php
b/lib/includes/formatters/EntityIdHtmlLinkFormatter.php
index 9467288..cdb7490 100644
--- a/lib/includes/formatters/EntityIdHtmlLinkFormatter.php
+++ b/lib/includes/formatters/EntityIdHtmlLinkFormatter.php
@@ -52,7 +52,7 @@
*
* @param EntityId $entityId
*
- * @return string
+ * @return string HTML
*/
public function formatEntityId( EntityId $entityId ) {
$title = $this->entityTitleLookup->getTitleForId( $entityId );
diff --git a/lib/includes/formatters/EntityIdLinkFormatter.php
b/lib/includes/formatters/EntityIdLinkFormatter.php
index d5a182d..4f06ddc 100644
--- a/lib/includes/formatters/EntityIdLinkFormatter.php
+++ b/lib/includes/formatters/EntityIdLinkFormatter.php
@@ -20,7 +20,7 @@
*
* @param EntityId $entityId
*
- * @return string
+ * @return string Wikitext
*/
public function formatEntityId( EntityId $entityId ) {
$title = parent::formatEntityId( $entityId );
diff --git a/lib/includes/formatters/EntityIdPlainLinkFormatter.php
b/lib/includes/formatters/EntityIdPlainLinkFormatter.php
index b718c93..8eb97f4 100644
--- a/lib/includes/formatters/EntityIdPlainLinkFormatter.php
+++ b/lib/includes/formatters/EntityIdPlainLinkFormatter.php
@@ -21,7 +21,7 @@
*
* @param EntityId $entityId
*
- * @return string
+ * @return string Wikitext
*/
public function formatEntityId( EntityId $entityId ) {
$title = parent::formatEntityId( $entityId );
diff --git a/lib/includes/formatters/EntityIdTitleFormatter.php
b/lib/includes/formatters/EntityIdTitleFormatter.php
index 6343008..1499599 100644
--- a/lib/includes/formatters/EntityIdTitleFormatter.php
+++ b/lib/includes/formatters/EntityIdTitleFormatter.php
@@ -33,7 +33,7 @@
*
* @param EntityId $entityId
*
- * @return string
+ * @return string Plain text
*/
public function formatEntityId( EntityId $entityId ) {
$title = $this->titleLookup->getTitleForId( $entityId );
diff --git a/lib/includes/formatters/EntityIdValueFormatter.php
b/lib/includes/formatters/EntityIdValueFormatter.php
index 54fc678..dbf6988 100644
--- a/lib/includes/formatters/EntityIdValueFormatter.php
+++ b/lib/includes/formatters/EntityIdValueFormatter.php
@@ -8,6 +8,8 @@
use Wikibase\DataModel\Services\EntityId\EntityIdFormatter;
/**
+ * A simple wrapper that forwards formatting of an EntityIdValue object to an
EntityIdFormatter.
+ *
* @since 0.5
*
* @licence GNU GPL v2+
@@ -38,7 +40,8 @@
* @param EntityIdValue $value
*
* @throws InvalidArgumentException
- * @return string Text
+ * @return string Either plain text, wikitext or HTML, depending on the
EntityIdFormatter
+ * provided.
*/
public function format( $value ) {
if ( !( $value instanceof EntityIdValue ) ) {
diff --git a/lib/includes/formatters/HtmlTimeFormatter.php
b/lib/includes/formatters/HtmlTimeFormatter.php
index 5f5d52c..2f498fa 100644
--- a/lib/includes/formatters/HtmlTimeFormatter.php
+++ b/lib/includes/formatters/HtmlTimeFormatter.php
@@ -9,6 +9,14 @@
use ValueFormatters\ValueFormatterBase;
/**
+ * A value formatter that creates a basic, single-line HTML representation of
a TimeValue's date,
+ * time and calendar model. The calendar model is added in superscript when
needed, either because
+ * it's not obvious (e.g. a date in 1800 could be Julian or Gregorian) or
because it's different
+ * from what the parsers would detect (where 1582 and before is Julian, and
1583 and later is
+ * Gregorian).
+ *
+ * @see Wikibase\Lib\TimeDetailsFormatter
+ *
* @since 0.5
*
* @license GNU GPL v2+
@@ -30,9 +38,13 @@
/**
* @param FormatterOptions|null $options
- * @param ValueFormatter $dateTimeFormatter
+ * @param ValueFormatter $dateTimeFormatter A value formatter that
accepts TimeValue objects and
+ * returns the formatted date and time, but not the calendar model.
Must return HTML.
*/
- public function __construct( FormatterOptions $options = null,
ValueFormatter $dateTimeFormatter ) {
+ public function __construct(
+ FormatterOptions $options = null,
+ ValueFormatter $dateTimeFormatter
+ ) {
parent::__construct( $options );
$this->dateTimeFormatter = $dateTimeFormatter;
diff --git a/lib/includes/formatters/TimeDetailsFormatter.php
b/lib/includes/formatters/TimeDetailsFormatter.php
index b08426c..5ce416c 100644
--- a/lib/includes/formatters/TimeDetailsFormatter.php
+++ b/lib/includes/formatters/TimeDetailsFormatter.php
@@ -12,6 +12,8 @@
/**
* Formatter for rendering the details of a TimeValue (most useful for diffs)
in HTML.
*
+ * @see Wikibase\Lib\HtmlTimeFormatter
+ *
* @since 0.5
*
* @licence GNU GPL v2+
diff --git a/purtle/src/RdfWriterFactory.php b/purtle/src/RdfWriterFactory.php
index 46a04f0..3d29392 100644
--- a/purtle/src/RdfWriterFactory.php
+++ b/purtle/src/RdfWriterFactory.php
@@ -5,8 +5,6 @@
use InvalidArgumentException;
/**
- * Factory for RdfWriters
- *
* @since 0.5
*
* @licence GNU GPL v2+
diff --git a/repo/includes/Parsers/YearTimeParser.php
b/repo/includes/Parsers/YearTimeParser.php
index 4cb27c7..b94038f 100644
--- a/repo/includes/Parsers/YearTimeParser.php
+++ b/repo/includes/Parsers/YearTimeParser.php
@@ -12,6 +12,11 @@
use ValueParsers\ValueParser;
/**
+ * A straight parser that accepts various strings representing a year, and
only a year. Accepts
+ * years before common era as well as optional thousands separators. Should be
called after
+ * YearMonthTimeParser when you want to accept both formats, because strings
like "1 999" may either
+ * represent a month and a year or a year with digit grouping.
+ *
* @since 0.5
*
* @licence GNU GPL v2+
--
To view, visit https://gerrit.wikimedia.org/r/260565
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I333d0645248e07a73f8df08a7616680f7314838f
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
