Docs: Improve JSDoc for `pointer.js`.

Props maartenleenders, dfangstrom.
Fixes #44325.


git-svn-id: https://develop.svn.wordpress.org/trunk@43346 602fd350-edb4-49c9-b593-d223f7449a82

1 files changed, 141 insertions, 7 deletions

diff --git a/src/js/_enqueues/lib/pointer.js b/src/js/_enqueues/lib/pointer.js
index a6b13c7fa5..9f67389004 100644
--- a/src/js/_enqueues/lib/pointer.js
+++ b/src/js/_enqueues/lib/pointer.js
@@ -1,14 +1,12 @@
 /* global wpPointerL10n */
+
 /**
- * Pointer jQuery widget.
+ * Initializes the wp-pointer widget using jQuery UI Widget Factory.
  */
 (function($){
 	var identifier = 0,
 		zindex = 9999;
 
-	/**
-	 * @class $.widget.wp.pointer
-	 */
 	$.widget('wp.pointer',/** @lends $.widget.wp.pointer.prototype */{
 		options: {
 			pointerClass: 'wp-pointer',
@@ -37,6 +35,14 @@
 			document: document
 		},
 
+		/**
+		 * A class that represents a WordPress pointer.
+		 *
+		 * @since 3.3.0
+		 * @private
+		 *
+		 * @constructs $.widget.wp.pointer
+		 */
 		_create: function() {
 			var positioning,
 				family;
@@ -59,6 +65,23 @@
 				.appendTo( this.options.document.body );
 		},
 
+		/**
+		 * Sets an option on the pointer instance.
+		 *
+		 * There are 4 special values that do something extra:
+		 *
+		 * - `document`     will transfer the pointer to the body of the new document
+		 *                  specified by the value.
+		 * - `pointerClass` will change the class of the pointer element.
+		 * - `position`     will reposition the pointer.
+		 * - `content`      will update the content of the pointer.
+		 *
+		 * @since 3.3.0
+		 * @private
+		 *
+		 * @param {string} key   The key of the option to set.
+		 * @param {*}      value The value to set the option to.
+		 */
 		_setOption: function( key, value ) {
 			var o   = this.options,
 				tip = this.pointer;
@@ -85,15 +108,45 @@
 			}
 		},
 
+		/**
+		 * Removes the pointer element from of the DOM.
+		 *
+		 * Makes sure that the widget and all associated bindings are destroyed.
+		 *
+		 * @since 3.3.0
+		 */
 		destroy: function() {
 			this.pointer.remove();
 			$.Widget.prototype.destroy.call( this );
 		},
 
+		/**
+		 * Returns the pointer element.
+		 *
+		 * @since 3.3.0
+		 *
+		 * @return {Object} Pointer The pointer object.
+		 */
 		widget: function() {
 			return this.pointer;
 		},
 
+		/**
+		 * Updates the content of the pointer.
+		 *
+		 * This function doesn't update the content of the pointer itself. That is done
+		 * by the `_update` method. This method will make sure that the `_update` method
+		 * is called with the right content.
+		 *
+		 * The content in the options can either be a string or a callback. If it is a
+		 * callback the result of this callback is used as the content.
+		 *
+		 * @since 3.3.0
+		 *
+		 * @param {Object} event The event that caused the update.
+		 *
+		 * @return {Promise} Resolves when the update has been executed.
+		 */
 		update: function( event ) {
 			var self = this,
 				o    = this.options,
@@ -124,8 +177,15 @@
 		},
 
 		/**
-		 * Update is separated into two functions to allow events to defer
-		 * updating the pointer (e.g. fetch content with ajax, etc).
+		 * Updates the content of the pointer.
+		 *
+		 * Will make sure that the pointer is correctly positioned.
+		 *
+		 * @since 3.3.0
+		 * @private
+		 *
+		 * @param {Object} event   The event that caused the update.
+		 * @param {*}      content The content object. Either a string or a jQuery tree.
 		 */
 		_update: function( event, content ) {
 			var buttons,
@@ -134,7 +194,8 @@
 			if ( ! content )
 				return;
 
-			this.pointer.stop(); // Kill any animations on the pointer.
+			// Kill any animations on the pointer.
+			this.pointer.stop();
 			this.content.html( content );
 
 			buttons = o.buttons.call( this.element[0], event, this._handoff() );
@@ -145,6 +206,14 @@
 			this.reposition();
 		},
 
+		/**
+		 * Repositions the pointer.
+		 *
+		 * Makes sure the pointer is the correct size for its content and makes sure it
+		 * is positioned to point to the right element.
+		 *
+		 * @since 3.3.0
+		 */
 		reposition: function() {
 			var position;
 
@@ -166,6 +235,11 @@
 			this.repoint();
 		},
 
+		/**
+		 * Sets the arrow of the pointer to the correct side of the pointer element.
+		 *
+		 * @since 3.3.0
+		 */
 		repoint: function() {
 			var o = this.options,
 				edge;
@@ -182,6 +256,17 @@
 			this.pointer.addClass( 'wp-pointer-' + edge );
 		},
 
+		/**
+		 * Calculates the correct position based on a position in the settings.
+		 *
+		 * @since 3.3.0
+		 * @private
+		 *
+		 * @param {string|Object} position Either a side of a pointer or an object
+		 *                                 containing a pointer.
+		 *
+		 * @return {Object} result  An object containing position related data.
+		 */
 		_processPosition: function( position ) {
 			var opposite = {
 					top: 'bottom',
@@ -218,6 +303,17 @@
 			return result;
 		},
 
+		/**
+		 * Opens the pointer.
+		 *
+		 * Only opens the pointer widget in case it is closed and not disabled, and
+		 * calls 'update' before doing so. Calling update makes sure that the pointer
+		 * is correctly sized and positioned.
+		 *
+		 * @since 3.3.0
+		 *
+		 * @param {Object} event The event that triggered the opening of this pointer.
+		 */
 		open: function( event ) {
 			var self = this,
 				o    = this.options;
@@ -230,6 +326,14 @@
 			});
 		},
 
+		/**
+		 * Opens and shows the pointer element.
+		 *
+		 * @since 3.3.0
+		 * @private
+		 *
+		 * @param {Object} event An event object.
+		 */
 		_open: function( event ) {
 			var self = this,
 				o    = this.options;
@@ -248,6 +352,13 @@
 			}));
 		},
 
+		/**
+		 * Closes and hides the pointer element.
+		 *
+		 * @since 3.3.0
+		 *
+		 * @param {Object} event An event object.
+		 */
 		close: function( event ) {
 			if ( !this.active || this.options.disabled )
 				return;
@@ -263,11 +374,23 @@
 			}));
 		},
 
+		/**
+		 * Puts the pointer on top by increasing the z-index.
+		 *
+		 * @since 3.3.0
+		 */
 		sendToTop: function() {
 			if ( this.active )
 				this.pointer.css( 'z-index', zindex++ );
 		},
 
+		/**
+		 * Toggles the element between shown and hidden.
+		 *
+		 * @since 3.3.0
+		 *
+		 * @param {Object} event An event object.
+		 */
 		toggle: function( event ) {
 			if ( this.pointer.is(':hidden') )
 				this.open( event );
@@ -275,6 +398,17 @@
 				this.close( event );
 		},
 
+		/**
+		 * Extends the pointer and the widget element with the supplied parameter, which
+		 * is either an element or a function.
+		 *
+		 * @since 3.3.0
+		 * @private
+		 *
+		 * @param {Object} extend The object to be merged into the original object.
+		 *
+		 * @return {Object} The extended object.
+		 */
 		_handoff: function( extend ) {
 			return $.extend({
 				pointer: this.pointer,