Changeset 43346

Timestamp:

06/14/2018 03:13:19 PM (7 years ago)

Author:

atimmer

Message:

Docs: Improve JSDoc for pointer.js.

Props maartenleenders, dfangstrom.
Fixes #44325.

File:

• trunk/src/js/_enqueues/lib/pointer.js (modified) (17 diffs)

trunk/src/js/_enqueues/lib/pointer.js

@@ -1 +1 @@
 /* global wpPointerL10n */
+
 /**
- * Pointer jQuery widget.
+ * Initializes the wp-pointer widget using jQuery UI Widget Factory.
  */
 (function($){
@@ -7 +8 @@
         zindex = 9999;
 
-    /**
-     * @class $.widget.wp.pointer
-     */
     $.widget('wp.pointer',/** @lends $.widget.wp.pointer.prototype */{
         options: {
@@ -38 +36 @@
         },
 
+        /**
+         * A class that represents a WordPress pointer.
+         *
+         * @since 3.3.0
+         * @private
+         *
+         * @constructs $.widget.wp.pointer
+         */
         _create: function() {
             var positioning,
@@ -60 +66 @@
         },
 
+        /**
+         * 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,
@@ -86 +109 @@
         },
 
+        /**
+         * 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();
@@ -91 +121 @@
         },
 
+        /**
+         * 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,
@@ -125 +178 @@
 
         /**
-         * 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 ) {
@@ -135 +195 @@
                 return;
 
-            this.pointer.stop(); // Kill any animations on the pointer.
+            // Kill any animations on the pointer.
+            this.pointer.stop();
             this.content.html( content );
 
@@ -146 +207 @@
         },
 
+        /**
+         * 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;
@@ -167 +236 @@
         },
 
+        /**
+         * Sets the arrow of the pointer to the correct side of the pointer element.
+         *
+         * @since 3.3.0
+         */
         repoint: function() {
             var o = this.options,
@@ -183 +257 @@
         },
 
+        /**
+         * 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 = {
@@ -219 +304 @@
         },
 
+        /**
+         * 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,
@@ -231 +327 @@
         },
 
+        /**
+         * Opens and shows the pointer element.
+         *
+         * @since 3.3.0
+         * @private
+         *
+         * @param {Object} event An event object.
+         */
         _open: function( event ) {
             var self = this,
@@ -249 +353 @@
         },
 
+        /**
+         * 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 )
@@ -264 +375 @@
         },
 
+        /**
+         * Puts the pointer on top by increasing the z-index.
+         *
+         * @since 3.3.0
+         */
         sendToTop: function() {
             if ( this.active )
@@ -269 +385 @@
         },
 
+        /**
+         * 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') )
@@ -276 +399 @@
         },
 
+        /**
+         * 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({