watchlist: cleanup various method/variable names and comments in watchlist/store code

Change-Id: I70a55d5b4ea38f92132a15da3feb314b6b5bb013

2 files changed, 14 insertions, 3 deletions

diff --git a/includes/watcheditem/WatchedItemStore.php b/includes/watcheditem/WatchedItemStore.php
index bd4360eb85e0..ec25002d9c9e 100644
--- a/includes/watcheditem/WatchedItemStore.php
+++ b/includes/watcheditem/WatchedItemStore.php
@@ -1103,6 +1103,14 @@ class WatchedItemStore implements WatchedItemStoreInterface, StatsdAwareInterfac
 		return "{$target->getNamespace()}:{$target->getDBkey()}";
 	}
 
+	/**
+	 * @param UserIdentity $user
+	 * @param LinkTarget $title
+	 * @param WatchedItem $item
+	 * @param bool $force
+	 * @param int|bool $oldid The ID of the last revision that the user viewed
+	 * @return bool|string|null
+	 */
 	private function getNotificationTimestamp(
 		UserIdentity $user, LinkTarget $title, $item, $force, $oldid
 	) {
@@ -1112,7 +1120,8 @@ class WatchedItemStore implements WatchedItemStoreInterface, StatsdAwareInterfac
 		}
 
 		$oldRev = $this->revisionLookup->getRevisionById( $oldid );
-		if ( !$this->revisionLookup->getNextRevision( $oldRev, $title ) ) {
+		$nextRev = $this->revisionLookup->getNextRevision( $oldRev, $title );
+		if ( !$nextRev ) {
 			// Oldid given and is the latest revision for this title; clear the timestamp.
 			return null;
 		}
@@ -1129,6 +1138,8 @@ class WatchedItemStore implements WatchedItemStoreInterface, StatsdAwareInterfac
 		// Oldid given and isn't the latest; update the timestamp.
 		// This will result in no further notification emails being sent!
 		$notificationTimestamp = $this->revisionLookup->getTimestampFromId( $oldid );
+		// @FIXME: this should use getTimestamp() for consistency with updates on new edits
+		// $notificationTimestamp = $nextRev->getTimestamp(); // first unseen revision timestamp
 
 		// We need to go one second to the future because of various strict comparisons
 		// throughout the codebase
diff --git a/includes/watcheditem/WatchedItemStoreInterface.php b/includes/watcheditem/WatchedItemStoreInterface.php
index 5ff29d0d5d60..1cf328852927 100644
--- a/includes/watcheditem/WatchedItemStoreInterface.php
+++ b/includes/watcheditem/WatchedItemStoreInterface.php
@@ -239,7 +239,7 @@ interface WatchedItemStoreInterface {
 	 * @param UserIdentity $editor The editor that triggered the update. Their notification
 	 *  timestamp will not be updated(they have already seen it)
 	 * @param LinkTarget $target The target to update timestamps for
-	 * @param string $timestamp Set the update timestamp to this value
+	 * @param string $timestamp Set the update (first unseen revision) timestamp to this value
 	 *
 	 * @return int[] Array of user IDs the timestamp has been updated for
 	 */
@@ -341,7 +341,7 @@ interface WatchedItemStoreInterface {
 	 * @param string|null $timestamp Value of wl_notificationtimestamp from the DB
 	 * @param UserIdentity $user
 	 * @param LinkTarget $target
-	 * @return string|null TS_MW timestamp or null if all revision were seen
+	 * @return string|null TS_MW timestamp of first unseen revision or null if there isn't one
 	 */
 	public function getLatestNotificationTimestamp(
 		$timestamp, UserIdentity $user, LinkTarget $target );