From cdae062d47ba8da13624693f54c6efc25ac00490 Mon Sep 17 00:00:00 2001
From: Umherirrender <umherirrender_de.wp@web.de>
Date: Fri, 15 Feb 2019 21:23:02 +0100
Subject: [PATCH] Improve param docs and add @var to clarify types

Change-Id: I44f872b3a2921e75aab8e22fec57735f17ee1d8b
---
 includes/UserLocator.php              |  2 +-
 includes/api/ApiEchoNotifications.php |  4 ++--
 includes/jobs/NotificationJob.php     |  1 +
 includes/model/Event.php              | 13 +++++++++----
 4 files changed, 13 insertions(+), 7 deletions(-)

diff --git a/includes/UserLocator.php b/includes/UserLocator.php
index 2e49e7391..90354e09f 100644
--- a/includes/UserLocator.php
+++ b/includes/UserLocator.php
@@ -9,7 +9,7 @@ class EchoUserLocator {
 	 *
 	 * @param EchoEvent $event
 	 * @param int $batchSize
-	 * @return User[]
+	 * @return User[]|Iterator<User>
 	 */
 	public static function locateUsersWatchingTitle( EchoEvent $event, $batchSize = 500 ) {
 		$title = $event->getTitle();
diff --git a/includes/api/ApiEchoNotifications.php b/includes/api/ApiEchoNotifications.php
index 9b387e32f..fed7001ac 100644
--- a/includes/api/ApiEchoNotifications.php
+++ b/includes/api/ApiEchoNotifications.php
@@ -141,7 +141,7 @@ class ApiEchoNotifications extends ApiQueryBase {
 	 * Internal method for getting the property 'list' data for individual section
 	 * @param User $user
 	 * @param string $section 'alert' or 'message'
-	 * @param string $filter 'all', 'read' or 'unread'
+	 * @param string[] $filter 'all', 'read' or 'unread'
 	 * @param int $limit
 	 * @param string $continue
 	 * @param string $format
@@ -184,7 +184,7 @@ class ApiEchoNotifications extends ApiQueryBase {
 	 * of a set of sections or a single section
 	 * @param User $user
 	 * @param string[] $eventTypes
-	 * @param string $filter 'all', 'read' or 'unread'
+	 * @param string[] $filter 'all', 'read' or 'unread'
 	 * @param int $limit
 	 * @param string $continue
 	 * @param string $format
diff --git a/includes/jobs/NotificationJob.php b/includes/jobs/NotificationJob.php
index 009d3a74e..e9e271595 100644
--- a/includes/jobs/NotificationJob.php
+++ b/includes/jobs/NotificationJob.php
@@ -1,6 +1,7 @@
 <?php
 
 class EchoNotificationJob extends Job {
+	/** @var int */
 	private $eventId;
 
 	public function __construct( $title, $params ) {
diff --git a/includes/model/Event.php b/includes/model/Event.php
index 1ba6fa014..9049cb4a2 100644
--- a/includes/model/Event.php
+++ b/includes/model/Event.php
@@ -8,34 +8,39 @@ use MediaWiki\Logger\LoggerFactory;
  */
 class EchoEvent extends EchoAbstractEntity implements Bundleable {
 
+	/** @var string|null */
 	protected $type = null;
+	/** @var string|null|false */
 	protected $id = null;
+	/** @var string|null */
 	protected $variant = null;
 	/**
-	 * @var User
+	 * @var User|null
 	 */
 	protected $agent = null;
 
 	/**
 	 * Loaded dynamically on request
 	 *
-	 * @var Title
+	 * @var Title|null
 	 */
 	protected $title = null;
+	/** @var int|null */
 	protected $pageId = null;
 
 	/**
 	 * Loaded dynamically on request
 	 *
-	 * @var Revision
+	 * @var Revision|null
 	 */
 	protected $revision = null;
 
+	/** @var array */
 	protected $extra = [];
 
 	/**
 	 * Notification timestamp
-	 * @var string
+	 * @var string|null
 	 */
 	protected $timestamp = null;