WordPress.org
Get WordPress

Make WordPress Core

Changeset 47120


Ignore:
Timestamp:
01/29/2020 12:35:39 AM (6 years ago)
Author:
SergeyBiryukov
Message:

Docs: Improve comments in js/_enqueues/wp/revisions.js per the documentation standards.

Props passoniate.
Fixes #49177.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/js/_enqueues/wp/revisions.js

    r43347 r47120  
    2020    revisions.settings = window._wpRevisionsSettings || {};
    2121
    22     // For debugging
     22    // For debugging.
    2323    revisions.debug = false;
    2424
    … …  
    3535    };
    3636
    37     // Handy functions to help with positioning
     37    // Handy functions to help with positioning.
    3838    $.fn.allOffsets = function() {
    3939        var offset = this.offset() || {top: 0, left: 0}, win = $(window);
    … …  
    7272            this.revisions = options.revisions;
    7373
    74             // Listen for changes to the revisions or mode from outside
     74            // Listen for changes to the revisions or mode from outside.
    7575            this.listenTo( this.frame, 'update:revisions', this.receiveRevisions );
    7676            this.listenTo( this.frame, 'change:compareTwoMode', this.updateMode );
    7777
    78             // Listen for internal changes
     78            // Listen for internal changes.
    7979            this.on( 'change:from', this.handleLocalChanges );
    8080            this.on( 'change:to', this.handleLocalChanges );
    … …  
    8282            this.on( 'update:revisions', this.updateSliderSettings );
    8383
    84             // Listen for changes to the hovered revision
     84            // Listen for changes to the hovered revision.
    8585            this.on( 'change:hoveredRevision', this.hoverRevision );
    8686
    … …  
    106106                    ],
    107107                    value: null,
    108                     range: true // ensures handles cannot cross
     108                    range: true // Ensures handles cannot cross.
    109109                });
    110110            } else {
    … …  
    118118        },
    119119
    120         // Called when a revision is hovered
     120        // Called when a revision is hovered.
    121121        hoverRevision: function( model, value ) {
    122122            this.trigger( 'hovered:revision', value );
    123123        },
    124124
    125         // Called when `compareTwoMode` changes
     125        // Called when `compareTwoMode` changes.
    126126        updateMode: function( model, value ) {
    127127            this.set({ compareTwoMode: value });
    128128        },
    129129
    130         // Called when `from` or `to` changes in the local model
     130        // Called when `from` or `to` changes in the local model.
    131131        handleLocalChanges: function() {
    132132            this.frame.set({
    … …  
    136136        },
    137137
    138         // Receives revisions changes from outside the model
     138        // Receives revisions changes from outside the model.
    139139        receiveRevisions: function( from, to ) {
    140             // Bail if nothing changed
     140            // Bail if nothing changed.
    141141            if ( this.get('from') === from && this.get('to') === to ) {
    142142                return;
    … …  
    153153            revision: null,
    154154            offset: {},
    155             hovering: false, // Whether the mouse is hovering
    156             scrubbing: false // Whether the mouse is scrubbing
     155            hovering: false, // Whether the mouse is hovering.
     156            scrubbing: false // Whether the mouse is scrubbing.
    157157        },
    158158
    … …  
    256256                this.trigger( 'ensure:load', ids, from, to, deferred.promise() );
    257257                _.each( ids, _.bind( function( id ) {
    258                     // Remove anything that has an ongoing request
     258                    // Remove anything that has an ongoing request.
    259259                    if ( this.requests[ id ] ) {
    260260                        delete ids[ id ];
    261261                    }
    262                     // Remove anything we already have
     262                    // Remove anything we already have.
    263263                    if ( this.get( id ) ) {
    264264                        delete ids[ id ];
    … …  
    266266                }, this ) );
    267267                if ( ! request ) {
    268                     // Always include the ID that started this ensure
     268                    // Always include the ID that started this ensure.
    269269                    ids[ id ] = true;
    270270                    request   = this.load( _.keys( ids ) );
    … …  
    281281        },
    282282
    283         // Returns an array of proximal diffs
     283        // Returns an array of proximal diffs.
    284284        getClosestUnloaded: function( ids, centerId ) {
    285285            var self = this;
    … …  
    304304                    if ( 1 === num ) { // Already tried 1. This just isn't working. Give up.
    305305                        deferred.reject();
    306                     } else { // Request fewer diffs this time
     306                    } else { // Request fewer diffs this time.
    307307                        self._loadAll( allRevisionIds, centerId, Math.ceil( num / 2 ) ).done( function() {
    308308                            deferred.resolve();
    … …  
    318318        load: function( comparisons ) {
    319319            wp.revisions.log( 'load', comparisons );
    320             // Our collection should only ever grow, never shrink, so remove: false
     320            // Our collection should only ever grow, never shrink, so `remove: false`.
    321321            return this.fetch({ data: { compare: comparisons }, remove: false }).done( function() {
    322322                wp.revisions.log( 'load:complete', comparisons );
    … …  
    395395            this.diffs.set( this.get( 'diffData' ) );
    396396
    397             // Set up internal listeners
     397            // Set up internal listeners.
    398398            this.listenTo( this, 'change:from', this.changeRevisionHandler );
    399399            this.listenTo( this, 'change:to', this.changeRevisionHandler );
    … …  
    411411            } );
    412412
    413             // Start the router if browser supports History API
     413            // Start the router if browser supports History API.
    414414            if ( window.history && window.history.pushState ) {
    415415                this.router = new revisions.Router({ model: this });
    … …  
    430430
    431431            // If we were on the first revision before switching to two-handled mode,
    432             // bump the 'to' position over one
     432            // bump the 'to' position over one.
    433433            if ( value && 0 === toIndex ) {
    434434                this.set({
    … …  
    439439
    440440            // When switching back to single-handled mode, reset 'from' model to
    441             // one position before the 'to' model
    442             if ( ! value && 0 !== toIndex ) { // '! value' means switching to single-handled mode
     441            // one position before the 'to' model.
     442            if ( ! value && 0 !== toIndex ) { // '! value' means switching to single-handled mode.
    443443                this.set({
    444444                    from: this.revisions.at( toIndex - 1 ),
    … …  
    450450        updatedRevisions: function( from, to ) {
    451451            if ( this.get( 'compareTwoMode' ) ) {
    452                 // TODO: compare-two loading strategy
     452                // @todo Compare-two loading strategy.
    453453            } else {
    454454                this.diffs.loadAll( this.revisions.pluck('id'), to.id, 40 );
    … …  
    461461        },
    462462
    463         // So long as `from` and `to` are changed at the same time, the diff
    464         // will only be updated once. This is because Backbone updates all of
    465         // the changed attributes in `set`, and then fires the `change` events.
     463        /*
     464         * So long as `from` and `to` are changed at the same time, the diff
     465         * will only be updated once. This is because Backbone updates all of
     466         * the changed attributes in `set`, and then fires the `change` events.
     467         */
    466468        updateDiff: function( options ) {
    467469            var from, to, diffId, diff;
    … …  
    510512                    error: true
    511513                });
    512             } else if ( this._diffId === diff.id ) { // Make sure the current diff didn't change
     514            } else if ( this._diffId === diff.id ) { // Make sure the current diff didn't change.
    513515                this.trigger( 'update:diff', diff );
    514516            }
    … …  
    594596            _.bindAll( this, 'setWidth' );
    595597
    596             // Add the button view
     598            // Add the button view.
    597599            this.views.add( new revisions.view.Buttons({
    598600                model: this.model
    599601            }) );
    600602
    601             // Add the checkbox view
     603            // Add the checkbox view.
    602604            this.views.add( new revisions.view.Checkbox({
    603605                model: this.model
    604606            }) );
    605607
    606             // Prep the slider model
     608            // Prep the slider model.
    607609            var slider = new revisions.model.Slider({
    608610                frame: this.model,
    … …  
    610612            }),
    611613
    612             // Prep the tooltip model
     614            // Prep the tooltip model.
    613615            tooltip = new revisions.model.Tooltip({
    614616                frame: this.model,
    … …  
    617619            });
    618620
    619             // Add the tooltip view
     621            // Add the tooltip view.
    620622            this.views.add( new revisions.view.Tooltip({
    621623                model: tooltip
    622624            }) );
    623625
    624             // Add the tickmarks view
     626            // Add the tickmarks view.
    625627            this.views.add( new revisions.view.Tickmarks({
    626628                model: tooltip
    627629            }) );
    628630
    629             // Add the slider view
     631            // Add the slider view.
    630632            this.views.add( new revisions.view.Slider({
    631633                model: slider
    632634            }) );
    633635
    634             // Add the Metabox view
     636            // Add the Metabox view.
    635637            this.views.add( new revisions.view.Metabox({
    636638                model: this.model
    … …  
    673675    });
    674676
    675     // The tickmarks view
     677    // The tickmarks view.
    676678    revisions.view.Tickmarks = wp.Backbone.View.extend({
    677679        className: 'revisions-tickmarks',
    … …  
    687689            parentOffset = this.$el.parent().allOffsets();
    688690            if ( index === this.model.revisions.length - 1 ) {
    689                 // Last one
     691                // Last one.
    690692                offset = {
    691693                    rightPlusWidth: thisOffset.left - parentOffset.left + 1,
    … …  
    693695                };
    694696            } else {
    695                 // Normal tick
     697                // Normal tick.
    696698                tick = this.$('div:nth-of-type(' + (index + 1) + ')');
    697699                offset = tick.allPositions();
    … …  
    720722    });
    721723
    722     // The metabox view
     724    // The metabox view.
    723725    revisions.view.Metabox = wp.Backbone.View.extend({
    724726        className: 'revisions-meta',
    725727
    726728        initialize: function() {
    727             // Add the 'from' view
     729            // Add the 'from' view.
    728730            this.views.add( new revisions.view.MetaFrom({
    729731                model: this.model,
    … …  
    731733            }) );
    732734
    733             // Add the 'to' view
     735            // Add the 'to' view.
    734736            this.views.add( new revisions.view.MetaTo({
    735737                model: this.model
    … …  
    738740    });
    739741
    740     // The revision meta view (to be extended)
     742    // The revision meta view (to be extended).
    741743    revisions.view.Meta = wp.Backbone.View.extend({
    742744        template: wp.template('revisions-meta'),
    … …  
    761763    });
    762764
    763     // The revision meta 'from' view
     765    // The revision meta 'from' view.
    764766    revisions.view.MetaFrom = revisions.view.Meta.extend({
    765767        className: 'diff-meta diff-meta-from',
    … …  
    767769    });
    768770
    769     // The revision meta 'to' view
     771    // The revision meta 'to' view.
    770772    revisions.view.MetaTo = revisions.view.Meta.extend({
    771773        className: 'diff-meta diff-meta-to',
    … …  
    881883        },
    882884
    883         // Go to a specific model index
     885        // Go to a specific model index.
    884886        gotoModel: function( toIndex ) {
    885887            var attributes = {
    … …  
    896898        },
    897899
    898         // Go to the 'next' revision
     900        // Go to the 'next' revision.
    899901        nextRevision: function() {
    900902            var toIndex = this.model.revisions.indexOf( this.model.get('to') ) + 1;
    … …  
    902904        },
    903905
    904         // Go to the 'previous' revision
     906        // Go to the 'previous' revision.
    905907        previousRevision: function() {
    906908            var toIndex = this.model.revisions.indexOf( this.model.get('to') ) - 1;
    … …  
    957959
    958960        mouseMove: function( e ) {
    959             var zoneCount         = this.model.revisions.length - 1, // One fewer zone than models
    960                 sliderFrom        = this.$el.allOffsets()[this.direction], // "From" edge of slider
    961                 sliderWidth       = this.$el.width(), // Width of slider
    962                 tickWidth         = sliderWidth / zoneCount, // Calculated width of zone
    963                 actualX           = ( isRtl ? $(window).width() - e.pageX : e.pageX ) - sliderFrom, // Flipped for RTL - sliderFrom;
    964                 currentModelIndex = Math.floor( ( actualX  + ( tickWidth / 2 )  ) / tickWidth ); // Calculate the model index
     961            var zoneCount         = this.model.revisions.length - 1,       // One fewer zone than models.
     962                sliderFrom        = this.$el.allOffsets()[this.direction], // "From" edge of slider.
     963                sliderWidth       = this.$el.width(),                      // Width of slider.
     964                tickWidth         = sliderWidth / zoneCount,               // Calculated width of zone.
     965                actualX           = ( isRtl ? $(window).width() - e.pageX : e.pageX ) - sliderFrom, // Flipped for RTL - sliderFrom.
     966                currentModelIndex = Math.floor( ( actualX  + ( tickWidth / 2 )  ) / tickWidth );    // Calculate the model index.
    965967
    966968            // Ensure sane value for currentModelIndex.
    … …  
    971973            }
    972974
    973             // Update the tooltip mode
     975            // Update the tooltip mode.
    974976            this.model.set({ hoveredRevision: this.model.revisions.at( currentModelIndex ) });
    975977        },
    … …  
    988990
    989991            if ( this.model.get('compareTwoMode') ) {
    990                 // in RTL mode the 'left handle' is the second in the slider, 'right' is first
     992                // In RTL mode the 'left handle' is the second in the slider, 'right' is first.
    991993                handles.first()
    992994                    .toggleClass( 'to-handle', !! isRtl )
    … …  
    10201022                if ( view.model.get('compareTwoMode') ) {
    10211023                    handles = handle.parent().find('.ui-slider-handle');
    1022                     if ( handle.is( handles.first() ) ) { // We're the left handle
     1024                    if ( handle.is( handles.first() ) ) {
     1025                        // We're the left handle.
    10231026                        rightDragBoundary = handles.last().offset().left;
    10241027                        rightDragReset    = rightDragBoundary - sliderOffset;
    1025                     } else { // We're the right handle
     1028                    } else {
     1029                        // We're the right handle.
    10261030                        leftDragBoundary = handles.first().offset().left + handles.first().width();
    10271031                        leftDragReset    = leftDragBoundary - sliderOffset;
    … …  
    10441048        },
    10451049
    1046         // Responds to slide events
     1050        // Responds to slide events.
    10471051        slide: function( event, ui ) {
    10481052            var attributes, movedRevision;
    1049             // Compare two revisions mode
     1053            // Compare two revisions mode.
    10501054            if ( this.model.get('compareTwoMode') ) {
    1051                 // Prevent sliders from occupying same spot
     1055                // Prevent sliders from occupying same spot.
    10521056                if ( ui.values[1] === ui.values[0] ) {
    10531057                    return false;
    … …  
    10731077            movedRevision = this.model.revisions.at( this.getPosition( ui.value ) );
    10741078
    1075             // If we are scrubbing, a scrub to a revision is considered a hover
     1079            // If we are scrubbing, a scrub to a revision is considered a hover.
    10761080            if ( this.model.get('scrubbing') ) {
    10771081                attributes.hoveredRevision = movedRevision;
    … …  
    10831087        stop: function() {
    10841088            $( window ).off('mousemove.wp.revisions');
    1085             this.model.updateSliderSettings(); // To snap us back to a tick mark
     1089            this.model.updateSliderSettings(); // To snap us back to a tick mark.
    10861090            this.model.set({ scrubbing: false });
    10871091        }
    … …  
    11061110            this.model = options.model;
    11071111
    1108             // Maintain state and history when navigating
     1112            // Maintain state and history when navigating.
    11091113            this.listenTo( this.model, 'update:diff', _.debounce( this.updateUrl, 250 ) );
    11101114            this.listenTo( this.model, 'change:compareTwoMode', this.updateUrl );
Note: See TracChangeset for help on using the changeset viewer.