From 6a9a5e123c49862babf664367c26c89499fed4e0 Mon Sep 17 00:00:00 2001 From: atimmer Date: Thu, 28 Jun 2018 02:29:48 +0000 Subject: [PATCH] Docs: Improve JSDoc for `pointer.js`. Props maartenleenders, dfangstrom. Fixes #44325. Built from https://develop.svn.wordpress.org/trunk@43346 git-svn-id: http://core.svn.wordpress.org/trunk@43174 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-includes/js/wp-pointer.js | 148 +++++++++++++++++++++++++++++++++-- wp-includes/version.php | 2 +- 2 files changed, 142 insertions(+), 8 deletions(-) diff --git a/wp-includes/js/wp-pointer.js b/wp-includes/js/wp-pointer.js index a6b13c7fa5..9f67389004 100644 --- a/wp-includes/js/wp-pointer.js +++ b/wp-includes/js/wp-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, diff --git a/wp-includes/version.php b/wp-includes/version.php index 42100d88f6..5effc7fe71 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -4,7 +4,7 @@ * * @global string $wp_version */ -$wp_version = '5.0-alpha-43345'; +$wp_version = '5.0-alpha-43346'; /** * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.