From 1c2a76ae226582f048b6bb98db7c36061fdd44aa Mon Sep 17 00:00:00 2001
From: Kaldari <rkaldari@wikimedia.org>
Date: Mon, 26 Nov 2012 14:57:28 -0800
Subject: [PATCH] Adding comments and fixing some incorrect comments

Change-Id: Iab1be6ad8700630f2cf3f97b5d5edd542f1c85ec
---
 controller/NotificationController.php |  5 +++--
 formatters/BasicFormatter.php         | 15 +++++++++++----
 formatters/NotificationFormatter.php  |  2 +-
 model/Notification.php                |  2 +-
 special/SpecialNotifications.php      |  1 +
 5 files changed, 17 insertions(+), 8 deletions(-)

diff --git a/controller/NotificationController.php b/controller/NotificationController.php
index dde92baa4..44fba89bb 100644
--- a/controller/NotificationController.php
+++ b/controller/NotificationController.php
@@ -175,9 +175,10 @@ class EchoNotificationController {
 	 *
 	 * @param $event EchoEvent that the notification is for.
 	 * @param $user User to format the notification for.
-	 * @param $format string The format to show the notification in: text or html
+	 * @param $format string The format to show the notification in: text, html, or email
 	 * @param $type string The type of notification being distributed (e.g. email, notify)
-	 * @return string type description
+	 * @return string|array The formatted notification, or an array of subject
+	 *     and body (for emails), or an error message
 	 */
 	public static function formatNotification( $event, $user, $format = 'text', $type = 'notify' ) {
 		global $wgEchoNotificationFormatters;
diff --git a/formatters/BasicFormatter.php b/formatters/BasicFormatter.php
index 93939a4e2..d3b7c1ebc 100644
--- a/formatters/BasicFormatter.php
+++ b/formatters/BasicFormatter.php
@@ -70,9 +70,11 @@ class EchoBasicFormatter extends EchoNotificationFormatter {
 	}
 
 	/**
-	 * @param $event EchoEvent
-	 * @param $user User
-	 * @param $type string
+	 * Formats a notification
+	 *
+	 * @param $event EchoEvent that the notification is for.
+	 * @param $user User to format the notification for.
+	 * @param $type string The type of notification being distributed (e.g. email, notify)
 	 * @return array|string
 	 */
 	public function format( $event, $user, $type ) {
@@ -84,9 +86,13 @@ class EchoBasicFormatter extends EchoNotificationFormatter {
 			return $this->formatNotificationTitle( $event, $user )->text();
 		}
 
-		// Assume html
+		// Assume html as the format for the notification
+
+		// Build the notification title
 		$title = $this->formatNotificationTitle( $event, $user )->parse();
 		$output = Xml::tags( 'div', array( 'class' => 'mw-echo-title' ), $title ) . "\n";
+
+		// Build the notification content
 		if ( !is_null( $this->content ) ) {
 			$content = $this->formatContent( $event, $user );
 			$content .= ' ' . $this->formatTimestamp( $event->getTimestamp(), $user );
@@ -96,6 +102,7 @@ class EchoBasicFormatter extends EchoNotificationFormatter {
 			$output .= Xml::tags( 'div', array( 'class' => 'mw-echo-content' ), $content ) . "\n";
 		}
 
+		// Add the notification icon
 		if ( !is_null( $this->icon ) ) {
 			$output = Xml::tags( 'div',
 				array( 'class' => "mw-echo-icon mw-echo-icon-{$this->icon}" ),
diff --git a/formatters/NotificationFormatter.php b/formatters/NotificationFormatter.php
index 86391f696..0fc6bc348 100644
--- a/formatters/NotificationFormatter.php
+++ b/formatters/NotificationFormatter.php
@@ -46,7 +46,7 @@ abstract class EchoNotificationFormatter {
 	/**
 	 * Set the output format that the notification will be displayed in.
 	 *
-	 * @param $format string A valid output format (by default, 'text' and 'html' are allowed)
+	 * @param $format string A valid output format (by default, 'text', 'html', and 'email' are allowed)
 	 * @throws MWException
 	 */
 	public function setOutputFormat( $format ) {
diff --git a/model/Notification.php b/model/Notification.php
index b86a95981..ae5da267d 100644
--- a/model/Notification.php
+++ b/model/Notification.php
@@ -52,7 +52,7 @@ class EchoNotification {
 	}
 
 	/**
-	 * Adds this new object to the database.
+	 * Adds this new notification object to the database.
 	 */
 	protected function insert() {
 		$dbw = wfGetDB( DB_MASTER );
diff --git a/special/SpecialNotifications.php b/special/SpecialNotifications.php
index bfe36bfeb..33a693e42 100644
--- a/special/SpecialNotifications.php
+++ b/special/SpecialNotifications.php
@@ -45,6 +45,7 @@ class SpecialNotifications extends SpecialPage {
 			$event = EchoEvent::newFromRow( $row );
 			$class = 'mw-echo-notification';
 
+			// Retrieve the formatted notification to display
 			$formatted = EchoNotificationController::formatNotification( $event, $user, 'html' );
 
 			if ( $row->notification_read_timestamp === null ) {