Make WordPress Core

Changeset 43346


Ignore:
Timestamp:
06/14/2018 03:13:19 PM (6 years ago)
Author:
atimmer
Message:

Docs: Improve JSDoc for pointer.js.

Props maartenleenders, dfangstrom.
Fixes #44325.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/js/_enqueues/lib/pointer.js

    r43309 r43346  
    11/* global wpPointerL10n */
     2
    23/**
    3  * Pointer jQuery widget.
     4 * Initializes the wp-pointer widget using jQuery UI Widget Factory.
    45 */
    56(function($){
     
    78        zindex = 9999;
    89
    9     /**
    10      * @class $.widget.wp.pointer
    11      */
    1210    $.widget('wp.pointer',/** @lends $.widget.wp.pointer.prototype */{
    1311        options: {
     
    3836        },
    3937
     38        /**
     39         * A class that represents a WordPress pointer.
     40         *
     41         * @since 3.3.0
     42         * @private
     43         *
     44         * @constructs $.widget.wp.pointer
     45         */
    4046        _create: function() {
    4147            var positioning,
     
    6066        },
    6167
     68        /**
     69         * Sets an option on the pointer instance.
     70         *
     71         * There are 4 special values that do something extra:
     72         *
     73         * - `document`     will transfer the pointer to the body of the new document
     74         *                  specified by the value.
     75         * - `pointerClass` will change the class of the pointer element.
     76         * - `position`     will reposition the pointer.
     77         * - `content`      will update the content of the pointer.
     78         *
     79         * @since 3.3.0
     80         * @private
     81         *
     82         * @param {string} key   The key of the option to set.
     83         * @param {*}      value The value to set the option to.
     84         */
    6285        _setOption: function( key, value ) {
    6386            var o   = this.options,
     
    86109        },
    87110
     111        /**
     112         * Removes the pointer element from of the DOM.
     113         *
     114         * Makes sure that the widget and all associated bindings are destroyed.
     115         *
     116         * @since 3.3.0
     117         */
    88118        destroy: function() {
    89119            this.pointer.remove();
     
    91121        },
    92122
     123        /**
     124         * Returns the pointer element.
     125         *
     126         * @since 3.3.0
     127         *
     128         * @return {Object} Pointer The pointer object.
     129         */
    93130        widget: function() {
    94131            return this.pointer;
    95132        },
    96133
     134        /**
     135         * Updates the content of the pointer.
     136         *
     137         * This function doesn't update the content of the pointer itself. That is done
     138         * by the `_update` method. This method will make sure that the `_update` method
     139         * is called with the right content.
     140         *
     141         * The content in the options can either be a string or a callback. If it is a
     142         * callback the result of this callback is used as the content.
     143         *
     144         * @since 3.3.0
     145         *
     146         * @param {Object} event The event that caused the update.
     147         *
     148         * @return {Promise} Resolves when the update has been executed.
     149         */
    97150        update: function( event ) {
    98151            var self = this,
     
    125178
    126179        /**
    127          * Update is separated into two functions to allow events to defer
    128          * updating the pointer (e.g. fetch content with ajax, etc).
     180         * Updates the content of the pointer.
     181         *
     182         * Will make sure that the pointer is correctly positioned.
     183         *
     184         * @since 3.3.0
     185         * @private
     186         *
     187         * @param {Object} event   The event that caused the update.
     188         * @param {*}      content The content object. Either a string or a jQuery tree.
    129189         */
    130190        _update: function( event, content ) {
     
    135195                return;
    136196
    137             this.pointer.stop(); // Kill any animations on the pointer.
     197            // Kill any animations on the pointer.
     198            this.pointer.stop();
    138199            this.content.html( content );
    139200
     
    146207        },
    147208
     209        /**
     210         * Repositions the pointer.
     211         *
     212         * Makes sure the pointer is the correct size for its content and makes sure it
     213         * is positioned to point to the right element.
     214         *
     215         * @since 3.3.0
     216         */
    148217        reposition: function() {
    149218            var position;
     
    167236        },
    168237
     238        /**
     239         * Sets the arrow of the pointer to the correct side of the pointer element.
     240         *
     241         * @since 3.3.0
     242         */
    169243        repoint: function() {
    170244            var o = this.options,
     
    183257        },
    184258
     259        /**
     260         * Calculates the correct position based on a position in the settings.
     261         *
     262         * @since 3.3.0
     263         * @private
     264         *
     265         * @param {string|Object} position Either a side of a pointer or an object
     266         *                                 containing a pointer.
     267         *
     268         * @return {Object} result  An object containing position related data.
     269         */
    185270        _processPosition: function( position ) {
    186271            var opposite = {
     
    219304        },
    220305
     306        /**
     307         * Opens the pointer.
     308         *
     309         * Only opens the pointer widget in case it is closed and not disabled, and
     310         * calls 'update' before doing so. Calling update makes sure that the pointer
     311         * is correctly sized and positioned.
     312         *
     313         * @since 3.3.0
     314         *
     315         * @param {Object} event The event that triggered the opening of this pointer.
     316         */
    221317        open: function( event ) {
    222318            var self = this,
     
    231327        },
    232328
     329        /**
     330         * Opens and shows the pointer element.
     331         *
     332         * @since 3.3.0
     333         * @private
     334         *
     335         * @param {Object} event An event object.
     336         */
    233337        _open: function( event ) {
    234338            var self = this,
     
    249353        },
    250354
     355        /**
     356         * Closes and hides the pointer element.
     357         *
     358         * @since 3.3.0
     359         *
     360         * @param {Object} event An event object.
     361         */
    251362        close: function( event ) {
    252363            if ( !this.active || this.options.disabled )
     
    264375        },
    265376
     377        /**
     378         * Puts the pointer on top by increasing the z-index.
     379         *
     380         * @since 3.3.0
     381         */
    266382        sendToTop: function() {
    267383            if ( this.active )
     
    269385        },
    270386
     387        /**
     388         * Toggles the element between shown and hidden.
     389         *
     390         * @since 3.3.0
     391         *
     392         * @param {Object} event An event object.
     393         */
    271394        toggle: function( event ) {
    272395            if ( this.pointer.is(':hidden') )
     
    276399        },
    277400
     401        /**
     402         * Extends the pointer and the widget element with the supplied parameter, which
     403         * is either an element or a function.
     404         *
     405         * @since 3.3.0
     406         * @private
     407         *
     408         * @param {Object} extend The object to be merged into the original object.
     409         *
     410         * @return {Object} The extended object.
     411         */
    278412        _handoff: function( extend ) {
    279413            return $.extend({
Note: See TracChangeset for help on using the changeset viewer.