Numerous bits of method parameter documentation

Change-Id: Ie4b2657b5e010311b779aa587aa7fa9fc3f19abb

Echo.php

@@ -180,7 +180,10 @@ $wgHooks['LinksUpdateAfterInsert'][] = 'EchoHooks::onLinksUpdateAfterInsert';
 // The name of the backend to use for Echo, eg, Db, Redis, Zeromq
 $wgEchoBackendName = 'Db';
 
-// The backend object
+/**
+ * The backend object
+ * @var MWEchoBackend
+ */
 $wgEchoBackend = null;
 
 // Whether to turn on email batch function

Hooks.php

@@ -151,6 +151,12 @@ class EchoHooks {
 		return true;
 	}
 
+	/**
+	 * @param $subscription EchoSubscription
+	 * @param $event EchoEvent
+	 * @param $notifyTypes
+	 * @return bool
+	 */
 	public static function getNotificationTypes( $subscription, $event, &$notifyTypes ) {
 		$type = $event->getType();
 		$user = $subscription->getUser();
@@ -494,7 +500,7 @@ class EchoHooks {
 	/**
 	 * Handler for MakeGlobalVariablesScript hook.
 	 * @see http://www.mediawiki.org/wiki/Manual:Hooks/MakeGlobalVariablesScript
-	 * @param &$vars Variables to be added into the output
+	 * @param &$vars array Variables to be added into the output
 	 * @param $outputPage OutputPage instance calling the hook
 	 * @return bool true in all cases
 	 */
@@ -532,7 +538,7 @@ class EchoHooks {
 	/**
 	 * Handler for ArticleEditUpdateNewTalk hook.
 	 * @see http://www.mediawiki.org/wiki/Manual:Hooks/ArticleEditUpdateNewTalk
-	 * @param $page The WikiPage object of the talk page being updated
+	 * @param $page WikiPage The WikiPage object of the talk page being updated
 	 * @return bool
 	 */
 	static function abortNewTalkNotification( $page ) {
@@ -551,10 +557,10 @@ class EchoHooks {
 	/**
 	 * Handler for ArticleRollbackComplete hook.
 	 * @see http://www.mediawiki.org/wiki/Manual:Hooks/ArticleRollbackComplete
-	 * @param $page The article that was edited
-	 * @param $agent The user who did the rollback
-	 * @param $newRevision The revision the page was reverted back to
-	 * @param $oldRevision The revision of the top edit that was reverted
+	 * @param $page WikiPage The article that was edited
+	 * @param $agent User The user who did the rollback
+	 * @param $newRevision Revision The revision the page was reverted back to
+	 * @param $oldRevision Revision The revision of the top edit that was reverted
 	 * @return bool true in all cases
 	 */
 	static function onRollbackComplete( $page, $agent, $newRevision, $oldRevision ) {

api/ApiEchoNotifications.php

@@ -48,7 +48,7 @@ class ApiEchoNotifications extends ApiQueryBase {
 	 *
 	 * @param $user User the user to get notifications for
 	 * @param $unread Boolean true to get only unread notifications
-	 * @param $format string/bool false to not format any notifications, string to a specific output format
+	 * @param $format string|bool false to not format any notifications, string to a specific output format
 	 * @param $limit int The maximum number of notifications to return
 	 * @param $timestamp int The timestamp to start from
 	 * @param $offset int The notification event id to start from

formatters/BasicFormatter.php

@@ -26,7 +26,7 @@ class EchoBasicFormatter extends EchoNotificationFormatter {
 		$this->title['message'] = $params['title-message'];
 		$this->title['params'] = $params['title-params'];
 		$this->payload = array();
-		
+
 		if ( isset( $params['payload'] ) ) {
 			$this->payload = $params['payload'];
 		}
@@ -165,7 +165,7 @@ class EchoBasicFormatter extends EchoNotificationFormatter {
 
 		// Add timestamp
 		$content .= $this->formatTimestamp( $event->getTimestamp(), $user );
-		
+
 		$output .= Xml::tags( 'div', array( 'class' => 'mw-echo-content' ), $content ) . "\n";
 
 		// The state div is used to visually indicate read or unread status. This is
@@ -176,6 +176,11 @@ class EchoBasicFormatter extends EchoNotificationFormatter {
 		return $output;
 	}
 
+	/**
+	 * @param $event EchoEvent
+	 * @param $user User
+	 * @return string
+	 */
 	protected function formatDismissInterface( $event, $user ) {
 		$dismissTitle = wfMessage( 'echo-dismiss-title-' . $event->type )
 			->inLanguage( $user->getOption( 'language' ) )
@@ -188,6 +193,11 @@ class EchoBasicFormatter extends EchoNotificationFormatter {
 		return $dismiss;
 	}
 
+	/**
+	 * @param $event EchoEvent
+	 * @param $user User
+	 * @return string
+	 */
 	protected function formatNotificationTitle( $event, $user ) {
 		if ( $this->outputFormat === 'flyout' ) {
 			return $this->formatFragment( $this->flyoutTitle, $event, $user );
@@ -196,6 +206,12 @@ class EchoBasicFormatter extends EchoNotificationFormatter {
 		}
 	}
 
+	/**
+	 * @param $event EchoEvent
+	 * @param $user User
+	 * @param $type
+	 * @return string
+	 */
 	protected function formatEmail( $event, $user, $type ) {
 		$subject = $this->formatFragment( $this->email['subject'], $event, $user )->text();
 

formatters/EditFormatter.php

@@ -53,5 +53,4 @@ class EchoEditFormatter extends EchoBasicFormatter {
 			parent::processParam( $event, $param, $message, $user );
 		}
 	}
-
 }

formatters/NotificationFormatter.php

@@ -93,7 +93,7 @@ abstract class EchoNotificationFormatter {
 	 * Formats a timestamp (in a human-readable format if supported by
 	 *  MediaWiki)
 	 *
-	 * @param $ts Timestamp in some format compatible with wfTimestamp()
+	 * @param $ts string Timestamp in some format compatible with wfTimestamp()
 	 * @param $user User to format for. false to detect
 	 * @return string Type description
 	 */
@@ -115,7 +115,6 @@ abstract class EchoNotificationFormatter {
 	 *
 	 * @param $event EchoEvent that the notification is for.
 	 * @param $user User to format the notification for.
-	 * @param $parse boolean If true, parse the summary. If fasle, strip wikitext.
 	 * @return string The edit summary (or empty string)
 	 */
 	protected function formatSummary( $event, $user ) {

includes/DiscussionParser.php

@@ -90,10 +90,10 @@ abstract class EchoDiscussionParser {
 	/**
 	 * For an action taken on a talk page, notify users whose user pages
 	 * are linked.
-	 * @param $header The subject line for the discussion.
-	 * @param $content The content of the post, as a wikitext string.
+	 * @param $header string The subject line for the discussion.
+	 * @param $content string The content of the post, as a wikitext string.
 	 * @param $revision Revision object.
-	 * @param $agent The user who made the comment.
+	 * @param $agent User The user who made the comment.
 	 */
 	public static function generateMentionEvents( $header, $content, $revision, $agent ) {
 		$title = $revision->getTitle();

includes/EchoBackend.php

@@ -34,6 +34,8 @@ abstract class MWEchoBackend {
 	/**
 	 * Get the enabled events for a user, which excludes user-dismissed events
 	 * from the general enabled events
+	 * @param $user User
+	 * @param $outputFormat string
 	 * @return array
 	 */
 	protected function getUserEnabledEvents( $user, $outputFormat ) {

model/Subscription.php

@@ -1,8 +1,17 @@
 <?php
 
 class EchoSubscription {
+	/**
+	 * @var $user User
+	 */
 	private $user = null;
+	/**
+	 * @var $event EchoEvent
+	 */
 	private $event = null;
+	/**
+	 * @var $title Title
+	 */
 	private $title = null;
 	private $notificationTypes = null;
 	private $dirty = false;