From 9a6358db9c0d9782f14478118d3b1b335b1bbca6 Mon Sep 17 00:00:00 2001
From: Timo Tijhof <krinklemail@gmail.com>
Date: Wed, 5 Feb 2014 15:21:28 -0800
Subject: [PATCH] mediawiki.page.watch.ajax: Add jsduck documentation

Change-Id: I8658cb2b9c00410d260622f89730d47d1eb2cc28
---
 maintenance/jsduck/categories.json            |  6 ++++
 maintenance/jsduck/config.json                |  1 +
 .../mediawiki.page.watch.ajax.js              | 34 +++++++++----------
 3 files changed, 24 insertions(+), 17 deletions(-)

diff --git a/maintenance/jsduck/categories.json b/maintenance/jsduck/categories.json
index bbe18607ae..875e2f5218 100644
--- a/maintenance/jsduck/categories.json
+++ b/maintenance/jsduck/categories.json
@@ -44,6 +44,12 @@
 					"mw.language*",
 					"mw.cldr"
 				]
+			},
+			{
+				"name": "Page",
+				"classes": [
+					"mw.page*"
+				]
 			}
 		]
 	},
diff --git a/maintenance/jsduck/config.json b/maintenance/jsduck/config.json
index d0e26284de..8be5b03adc 100644
--- a/maintenance/jsduck/config.json
+++ b/maintenance/jsduck/config.json
@@ -21,6 +21,7 @@
 		"../../resources/mediawiki.action/mediawiki.action.edit.js",
 		"../../resources/mediawiki.action/mediawiki.action.view.postEdit.js",
 		"../../resources/mediawiki.page/mediawiki.page.startup.js",
+		"../../resources/mediawiki.page/mediawiki.page.watch.ajax.js",
 		"../../resources/mediawiki.api",
 		"../../resources/mediawiki.language",
 		"../../resources/jquery/jquery.localize.js",
diff --git a/resources/mediawiki.page/mediawiki.page.watch.ajax.js b/resources/mediawiki.page/mediawiki.page.watch.ajax.js
index ef287c4324..998a8c2a6b 100644
--- a/resources/mediawiki.page/mediawiki.page.watch.ajax.js
+++ b/resources/mediawiki.page/mediawiki.page.watch.ajax.js
@@ -1,20 +1,20 @@
 /**
  * Animate watch/unwatch links to use asynchronous API requests to
  * watch pages, rather than navigating to a different URI.
+ *
+ * @class mw.page.watch.ajax
  */
 ( function ( mw, $ ) {
-	/**
-	 * The name of the page to watch or unwatch.
-	 */
+	// The name of the page to watch or unwatch
 	var title = mw.config.get( 'wgRelevantPageName', mw.config.get( 'wgPageName' ) );
 
 	/**
 	 * Update the link text, link href attribute and (if applicable)
 	 * "loading" class.
 	 *
-	 * @param $link {jQuery} Anchor tag of (un)watch link.
-	 * @param action {String} One of 'watch', 'unwatch'.
-	 * @param state {String} [optional] 'idle' or 'loading'. Default is 'idle'.
+	 * @param {jQuery} $link Anchor tag of (un)watch link
+	 * @param {string} action One of 'watch', 'unwatch'
+	 * @param {string} [state="idle"] 'idle' or 'loading'. Default is 'idle'
 	 */
 	function updateWatchLink( $link, action, state ) {
 		var accesskeyTip, msgKey, $li, otherAction;
@@ -25,12 +25,10 @@
 		accesskeyTip = $link.attr( 'title' ).match( mw.util.tooltipAccessKeyRegexp );
 		$li = $link.closest( 'li' );
 
-		/**
-		 * Trigger a 'watchpage' event for this List item.
-		 * Announce the otherAction value as the first param.
-		 * Used to monitor the state of watch link.
-		 * TODO: Revise when system wide hooks are implemented
-		 */
+		// Trigger a 'watchpage' event for this List item.
+		// Announce the otherAction value as the first param.
+		// Used to monitor the state of watch link.
+		// TODO: Revise when system wide hooks are implemented
 		if ( state === undefined ) {
 			$li.trigger( 'watchpage.mw', otherAction );
 		}
@@ -62,16 +60,18 @@
 	}
 
 	/**
-	 * @todo This should be moved somewhere more accessible.
-	 * @param url {String}
-	 * @return {String} The extracted action, defaults to 'view'.
+	 * TODO: This should be moved somewhere more accessible.
+	 *
+	 * @private
+	 * @param {string} url
+	 * @return {string} The extracted action, defaults to 'view'
 	 */
 	function mwUriGetAction( url ) {
 		var action, actionPaths, key, i, m, parts;
 
 		actionPaths = mw.config.get( 'wgActionPaths' );
 
-		// @todo Does MediaWiki give action path or query param
+		// TODO: Does MediaWiki give action path or query param
 		// precedence ? If the former, move this to the bottom
 		action = mw.util.getParamValue( 'action', url );
 		if ( action !== null ) {
@@ -95,7 +95,7 @@
 		return 'view';
 	}
 
-	// Expose local methods
+	// Expose public methods
 	mw.page.watch = {
 		updateWatchLink: updateWatchLink
 	};
-- 
2.20.1