Update JSDoc types and comments to be more specific

For example: We know the HTML element we are dealing with is
always an <a> element.

I believe the small changes in this patch are all obvious and
non-controversial. Please let me know if you disagree.

Change-Id: I9fe15845affffdd0f5f0fd6ef7d6b607cb567ac7

src/actions.js

@@ -119,7 +119,7 @@ function getDwellDelay( type ) {
  *
  * @param {Gateway} gateway
  * @param {mw.Title} title
- * @param {Element} el
+ * @param {HTMLAnchorElement} el
  * @param {string} token The unique token representing the link interaction that
  *  triggered the fetch
  * @param {string} type One of the previewTypes.TYPE_… constants
@@ -216,7 +216,7 @@ export function fetch( gateway, title, el, token, type ) {
  * their mouse or by focussing it using their keyboard or an assistive device.
  *
  * @param {mw.Title} title
- * @param {Element} el
+ * @param {HTMLAnchorElement} el
  * @param {ext.popups.Measures} measures
  * @param {Gateway} gateway
  * @param {Function} generateToken
@@ -305,7 +305,7 @@ export function abandon() {
  * Represents the user clicking on a link with their mouse, keyboard, or an
  * assistive device.
  *
- * @param {Element} el
+ * @param {HTMLAnchorElement} el
  * @return {Object}
  */
 export function linkClick( el ) {

src/gateway/index.js

@@ -26,7 +26,7 @@
  * If the underlying request is successful and contains data for the requested title,
  * then the resulting promise will resolve. If not, then it will reject.
  *
- * @typedef {function(mw.Title, Element): AbortPromise<PreviewModel>} FetchPreviewForTitle
+ * @typedef {function(mw.Title, HTMLAnchorElement): AbortPromise<PreviewModel>} FetchPreviewForTitle
  */
 
 /**

src/gateway/reference.js

@@ -46,7 +46,7 @@ export default function createReferenceGateway() {
 
 	/**
 	 * @param {mw.Title} title
-	 * @param {Element} el
+	 * @param {HTMLAnchorElement} el
 	 * @return {AbortPromise<ReferencePreviewModel>}
 	 */
 	function fetchPreviewForTitle( title, el ) {
@@ -59,7 +59,7 @@ export default function createReferenceGateway() {
 			( !$referenceText.text().trim() && !$referenceText.children().length )
 		) {
 			return $.Deferred().reject(
-				'Footnote not found',
+				'Footnote not found or empty',
 				// Required to set `showNullPreview` to false and not open an error popup
 				{ textStatus: 'abort', xhr: { readyState: 0 } }
 			).promise( { abort() {} } );

src/integrations/mwpopups.js

@@ -6,16 +6,18 @@ import { previewTypes } from '../preview/model';
 
 /**
  * This function provides a mw.popups object which can be used by 3rd party
- * to interact with Popups. Currently it allows only to read isEnabled flag.
+ * to interact with Popups.
  *
  * @param {Redux.Store} store Popups store
  * @return {Object} external Popups interface
  */
 export default function createMwPopups( store ) {
 	return {
+		/**
+		 * @return {boolean} If Page Previews are currently active
+		 */
 		isEnabled: function isEnabled() {
 			return store.getState().preview.enabled[ previewTypes.TYPE_PAGE ];
 		}
 	};
-
 }

src/preview/model.js

@@ -108,7 +108,7 @@ export function createNullModel( title, url ) {
 /**
  * Determines the applicable popup type based on title and link element.
  *
- * @param {Element} el
+ * @param {HTMLAnchorElement} el
  * @param {mw.Map} config
  * @param {mw.Title} title
  * @return {string|null} One of the previewTypes.TYPE_… constants

src/reducers/eventLogging.js

@@ -125,7 +125,7 @@ function createClosingEvent( interaction ) {
  *
  * [0]: https://meta.wikimedia.org/wiki/Schema:Popups
  *
- * @param {Object} state
+ * @param {Object|undefined} state
  * @param {Object} action
  * @return {Object} The state resulting from reducing the action with the
  *  current state

src/reducers/pageviews.js

@@ -11,7 +11,7 @@ import nextState from './nextState';
  *
  * [0]: https://meta.wikimedia.org/wiki/Schema:VirtualPageViews
  *
- * @param {Object} state
+ * @param {Object|undefined} state
  * @param {Object} action
  * @return {Object} The state resulting from reducing the action with the
  *  current state

src/reducers/settings.js

@@ -4,7 +4,7 @@ import nextState from './nextState';
 /**
  * Reducer for actions that modify the state of the settings
  *
- * @param {Object} state
+ * @param {Object|undefined} state
  * @param {Object} action
  * @return {Object} state after action
  */

src/reducers/statsv.js

@@ -4,7 +4,7 @@ import nextState from './nextState';
 /**
  * Reducer for actions that may result in an event being logged via statsv.
  *
- * @param {Object} state
+ * @param {Object|undefined} state
  * @param {Object} action
  * @return {Object} state after action
  */