Improve param docs and add @var to clarify types

Change-Id: I44f872b3a2921e75aab8e22fec57735f17ee1d8b

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();

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

includes/jobs/NotificationJob.php

@@ -1,6 +1,7 @@
 <?php
 
 class EchoNotificationJob extends Job {
+	/** @var int */
 	private $eventId;
 
 	public function __construct( $title, $params ) {

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;