jenkins-bot has submitted this change and it was merged. Change subject: Enhance code documentation. ......................................................................
Enhance code documentation. Bug: T137965 Change-Id: Ice393838545f1545ee085ecdcddfa35f60b32ecd --- M modules/ext.RevisionSlider.DiffPage.js M modules/ext.RevisionSlider.HelpDialog.js M modules/ext.RevisionSlider.Pointer.js M modules/ext.RevisionSlider.PointerView.js M modules/ext.RevisionSlider.Revision.js M modules/ext.RevisionSlider.RevisionList.js M modules/ext.RevisionSlider.RevisionListView.js M modules/ext.RevisionSlider.Slider.js M modules/ext.RevisionSlider.SliderView.js M modules/ext.RevisionSlider.fetchRevisions.js 10 files changed, 342 insertions(+), 7 deletions(-) Approvals: Addshore: Looks good to me, approved jenkins-bot: Verified diff --git a/modules/ext.RevisionSlider.DiffPage.js b/modules/ext.RevisionSlider.DiffPage.js index 4d7dd3b..5857710 100644 --- a/modules/ext.RevisionSlider.DiffPage.js +++ b/modules/ext.RevisionSlider.DiffPage.js @@ -1,8 +1,19 @@ ( function ( mw, $ ) { + /** + * Module handling diff page reloading and the RevisionSlider browser history + * + * @constructor + */ var DiffPage = function () { }; $.extend( DiffPage.prototype, { + /** + * Refreshes the diff view with two given revision IDs + * + * @param {number} revId1 + * @param {number} revId2 + */ refresh: function ( revId1, revId2 ) { $( 'table.diff[data-mw="interface"]' ) .append( $( '<tr>' ) ) @@ -43,6 +54,13 @@ } ); }, + /** + * Pushes the current state onto the history stack + * + * @param {number} revId1 + * @param {number} revId2 + * @param {SliderView} sliderView + */ pushState: function ( revId1, revId2, sliderView ) { // IE8 and IE9 do not have history.pushState() if ( typeof history.pushState === 'function' ) { @@ -60,6 +78,9 @@ } }, + /** + * @param {SliderView} sliderView + */ initOnPopState: function ( sliderView ) { var self = this; window.addEventListener( 'popstate', function ( event ) { diff --git a/modules/ext.RevisionSlider.HelpDialog.js b/modules/ext.RevisionSlider.HelpDialog.js index 00cc000..e069350 100644 --- a/modules/ext.RevisionSlider.HelpDialog.js +++ b/modules/ext.RevisionSlider.HelpDialog.js @@ -2,6 +2,12 @@ // JSHint does not like OOJS' usage of "static" and "super" /*jshint -W024 */ + /** + * Module containing the RevisionSlider tutorial + * + * @param {Object} config + * @constructor + */ var HelpDialog = function ( config ) { HelpDialog.super.call( this, config ); }; @@ -22,7 +28,14 @@ ]; $.extend( HelpDialog.prototype, { + /** + * @type {OO.ui.PanelLayout[]} + */ slides: [], + + /** + * @type {number} + */ slidePointer: 0, initialize: function () { @@ -37,6 +50,9 @@ this.$body.append( this.stackLayout.$element ); }, + /** + * @return {OO.ui.PanelLayout} + */ getSlide1: function () { var slide = new OO.ui.PanelLayout( { $: this.$, padded: true, expanded: false } ); @@ -52,6 +68,9 @@ return slide; }, + /** + * @return {OO.ui.PanelLayout} + */ getSlide2: function () { var slide = new OO.ui.PanelLayout( { $: this.$, padded: true, expanded: false } ); @@ -65,6 +84,9 @@ return slide; }, + /** + * @return {OO.ui.PanelLayout} + */ getSlide3: function () { var slide = new OO.ui.PanelLayout( { $: this.$, padded: true, expanded: false } ); @@ -79,6 +101,9 @@ return slide; }, + /** + * @return {OO.ui.PanelLayout} + */ getSlide4: function () { var slide = new OO.ui.PanelLayout( { $: this.$, padded: true, expanded: false } ); @@ -92,6 +117,10 @@ return slide; }, + /** + * @param {string} action + * @return {OO.ui.Process} + */ getActionProcess: function ( action ) { if ( action === 'next' ) { this.stackLayout.setItem( this.slides[ ++this.slidePointer ] ); @@ -121,13 +150,16 @@ /** * Needed to set the initial height of the dialog * - * @return {int} + * @return {number} */ getBodyHeight: function () { return this.slides[ this.slidePointer ].$element.outerHeight( true ); } } ); + /** + * Shows the help dialog + */ HelpDialog.show = function () { var windowManager = new OO.ui.WindowManager(), dialogue = new HelpDialog( { size: 'medium' } ); diff --git a/modules/ext.RevisionSlider.Pointer.js b/modules/ext.RevisionSlider.Pointer.js index f3a88c1..12a58dc 100644 --- a/modules/ext.RevisionSlider.Pointer.js +++ b/modules/ext.RevisionSlider.Pointer.js @@ -1,11 +1,17 @@ ( function ( mw, $ ) { + /** + * Module containing logic for the revision pointers + * + * @param {string} id + * @constructor + */ var Pointer = function ( id ) { this.view = new mw.libs.revisionSlider.PointerView( this, id ); }; $.extend( Pointer.prototype, { /** - * @type {int} + * @type {number} */ position: 0, @@ -14,14 +20,23 @@ */ view: null, + /** + * @param {number} p + */ setPosition: function ( p ) { this.position = p; }, + /** + * @return {number} + */ getPosition: function () { return this.position; }, + /** + * @return {PointerView} + */ getView: function () { return this.view; } diff --git a/modules/ext.RevisionSlider.PointerView.js b/modules/ext.RevisionSlider.PointerView.js index c54fd31..960ac83 100644 --- a/modules/ext.RevisionSlider.PointerView.js +++ b/modules/ext.RevisionSlider.PointerView.js @@ -1,4 +1,11 @@ ( function ( mw, $ ) { + /** + * Module containing presentation logic for the revision pointers + * + * @param {Pointer} pointer + * @param {string} id + * @constructor + */ var PointerView = function ( pointer, id ) { this.pointer = pointer; this.id = id; @@ -13,12 +20,16 @@ /** * @type {Pointer} */ + pointer: null, /** * @type {jQuery} */ $html: null, + /** + * Initializes the DOM element + */ initialize: function () { this.$html = $( '<div>' ) .attr( 'id', this.id ) @@ -40,10 +51,20 @@ return this.$html; }, + /** + * Returns whether a pointer is the upper/new revision pointer based on its CSS class + * + * @return {boolean} + */ isUpperPointer: function () { return this.getElement().hasClass( 'mw-upper-pointer' ); }, + /** + * Returns the offset (margin-left) depending on whether its the upper or lower pointer + * + * @return {number} + */ getOffset: function () { return this.isUpperPointer() ? 16 : 0; }, @@ -56,6 +77,13 @@ return this.getElement().offsetParent().width() - pos - 16 - 15; }, + /** + * Moves the pointer to a position + * + * @param {number} posInPx + * @param {number} duration + * @return {jQuery} + */ animateTo: function ( posInPx, duration ) { var animatePos = { left: posInPx }; if ( this.getElement().css( 'direction' ) === 'rtl' ) { @@ -64,11 +92,26 @@ return this.getElement().animate( animatePos, duration ); }, + /** + * Slides the pointer to the revision it's pointing at + * + * @param {Slider} slider + * @param {number} duration + * @return {jQuery} + */ slideToPosition: function ( slider, duration ) { var relativePos = this.pointer.getPosition() - slider.getFirstVisibleRevisionIndex(); return this.animateTo( ( relativePos - 1 ) * slider.getView().revisionWidth, duration ); }, + /** + * Slides the pointer to the side of the slider when it's not in the current range of revisions + * + * @param {Slider} slider + * @param {boolean} posBeforeSlider + * @param {number} duration + * @return {jQuery} + */ slideToSide: function ( slider, posBeforeSlider, duration ) { if ( posBeforeSlider ) { return this.animateTo( this.getOffset() - 2 * slider.getView().revisionWidth, duration ); @@ -77,6 +120,13 @@ } }, + /** + * Decides based on its position whether the pointer should be sliding to the side or to its position + * + * @param {Slider} slider + * @param {number} duration + * @return {jQuery} + */ slideToSideOrPosition: function ( slider, duration ) { var firstVisibleRev = slider.getFirstVisibleRevisionIndex(), posBeforeSlider = this.pointer.getPosition() < firstVisibleRev, diff --git a/modules/ext.RevisionSlider.Revision.js b/modules/ext.RevisionSlider.Revision.js index d1cab14..2bbc78d 100644 --- a/modules/ext.RevisionSlider.Revision.js +++ b/modules/ext.RevisionSlider.Revision.js @@ -1,5 +1,9 @@ ( function ( mw, $ ) { /*global moment:false */ + /** + * @param {Object} data - Containing keys `id`, `size`, `comment`, `parsedcomment`, `timestamp`, `user` and `minor` + * @constructor + */ var Revision = function ( data ) { this.id = data.revid; this.size = data.size; @@ -12,12 +16,12 @@ $.extend( Revision.prototype, { /** - * @type {int} + * @type {number} */ id: 0, /** - * @type {int} + * @type {number} */ size: 0, @@ -47,34 +51,58 @@ user: '', /** - * @type {int} + * @type {number} */ relativeSize: 0, + /** + * @return {number} + */ getId: function () { return this.id; }, + /** + * @return {number} + */ getSize: function () { return this.size; }, + /** + * @return {boolean} + */ isMinor: function () { return this.minor; }, + /** + * @return {string} + */ getParsedComment: function () { return this.parsedComment; }, + /** + * @return {boolean} + */ hasEmptyComment: function () { return this.getComment().trim().length === 0; }, + /** + * @return {string} + */ getComment: function () { return this.comment; }, + /** + * Uses moment.js to format the date + * + * @param {string} rawDate + * @return {string} + */ formatDate: function ( rawDate ) { // Moment's offset works "backwards", as the number of minutes // behind UTC, so we need to make this number negative @@ -82,18 +110,30 @@ return moment( rawDate ).zone( offset ).format( 'HH:mm, D MMM YYYY' ); }, + /** + * @return {string} + */ getFormattedDate: function () { return this.formatDate( this.timestamp ); }, + /** + * @return {string} + */ getUser: function () { return this.user; }, + /** + * @param {number} size + */ setRelativeSize: function ( size ) { this.relativeSize = size; }, + /** + * @return {number} + */ getRelativeSize: function () { return this.relativeSize; } diff --git a/modules/ext.RevisionSlider.RevisionList.js b/modules/ext.RevisionSlider.RevisionList.js index ea87779..0c10001 100644 --- a/modules/ext.RevisionSlider.RevisionList.js +++ b/modules/ext.RevisionSlider.RevisionList.js @@ -1,4 +1,8 @@ ( function ( mw, $ ) { + /** + * @param {Revision[]} revs + * @constructor + */ var RevisionList = function ( revs ) { this.revisions = []; this.initialize( revs ); @@ -16,6 +20,11 @@ */ view: null, + /** + * Inititializes the RevisionList from a list of Revisions + * + * @param {Revision[]} revs + */ initialize: function ( revs ) { var i, rev; @@ -27,6 +36,9 @@ } }, + /** + * @return {number} + */ getBiggestChangeSize: function () { var max = 0, i; @@ -38,14 +50,23 @@ return max; }, + /** + * @return {Revision[]} + */ getRevisions: function () { return this.revisions; }, + /** + * @return {number} + */ getLength: function () { return this.revisions.length; }, + /** + * @return {RevisionListView} + */ getView: function () { return this.view; } diff --git a/modules/ext.RevisionSlider.RevisionListView.js b/modules/ext.RevisionSlider.RevisionListView.js index ed6ebc0..2d7098d 100644 --- a/modules/ext.RevisionSlider.RevisionListView.js +++ b/modules/ext.RevisionSlider.RevisionListView.js @@ -1,4 +1,8 @@ ( function ( mw, $ ) { + /** + * @param {RevisionList} revisionList + * @constructor + */ var RevisionListView = function ( revisionList ) { this.revisionList = revisionList; }; @@ -9,6 +13,10 @@ */ revisionList: null, + /** + * @param {number} revisionTickWidth + * @return {jQuery} + */ render: function ( revisionTickWidth ) { var $html = $( '<div>' ).addClass( 'mw-revisions' ), revs = this.revisionList.getRevisions(), @@ -49,6 +57,12 @@ return $html; }, + /** + * Generates the HTML for a tooltip that appears on hover above each revision on the slider + * + * @param {Revision} rev + * @return {string} + */ makeTooltip: function ( rev ) { var $tooltip = $( '<div>' ) .append( @@ -70,6 +84,12 @@ return $tooltip.html(); }, + /** + * Generates the HTML for the comment label + * + * @param {Revision} rev + * @return {string|jQuery} + */ makeCommentLine: function ( rev ) { if ( rev.hasEmptyComment() ) { return ''; diff --git a/modules/ext.RevisionSlider.Slider.js b/modules/ext.RevisionSlider.Slider.js index ae1f352..954508c 100644 --- a/modules/ext.RevisionSlider.Slider.js +++ b/modules/ext.RevisionSlider.Slider.js @@ -1,4 +1,10 @@ ( function ( mw, $ ) { + /** + * Module handling the slider logic of the RevisionSlider + * + * @param {RevisionList} revisions + * @constructor + */ var Slider = function ( revisions ) { this.revisions = revisions; this.view = new mw.libs.revisionSlider.SliderView( this ); @@ -10,8 +16,14 @@ */ revisions: null, + /** + * @type {number} + */ firstVisibleRevisionIndex: 0, + /** + * @type {number} + */ revisionsPerWindow: 0, /** @@ -19,42 +31,82 @@ */ view: null, + /** + * @return {RevisionList} + */ getRevisions: function () { return this.revisions; }, + /** + * @return {SliderView} + */ getView: function () { return this.view; }, + /** + * Sets the number of revisions that are visible at once (depending on browser window size) + * + * @param {number} n + */ setRevisionsPerWindow: function ( n ) { this.revisionsPerWindow = n; }, + /** + * @return {number} + */ getRevisionsPerWindow: function () { return this.revisionsPerWindow; }, + /** + * Returns the index of the first revision that is visible in the current window + * + * @return {number} + */ getFirstVisibleRevisionIndex: function () { return this.firstVisibleRevisionIndex; }, + /** + * Returns the index of the last revision that is visible in the current window + * + * @return {number} + */ getLastVisibleRevisionIndex: function () { return this.firstVisibleRevisionIndex + this.revisionsPerWindow - 1; }, + /** + * @return {boolean} + */ isAtStart: function () { return this.getFirstVisibleRevisionIndex() === 0 || this.revisions.getLength() <= this.revisionsPerWindow; }, + /** + * @return {boolean} + */ isAtEnd: function () { return this.getLastVisibleRevisionIndex() === this.revisions.getLength() - 1 || this.revisions.getLength() <= this.revisionsPerWindow; }, + /** + * Sets the index of the first revision that is visible in the current window + * + * @param {number} value + */ setFirstVisibleRevisionIndex: function ( value ) { this.firstVisibleRevisionIndex = value; }, + /** + * Sets the new firstVisibleRevisionIndex after sliding in a direction + * + * @param {number} direction - Either -1 or 1 + */ slide: function ( direction ) { var highestPossibleFirstRev = this.revisions.getLength() - this.revisionsPerWindow; diff --git a/modules/ext.RevisionSlider.SliderView.js b/modules/ext.RevisionSlider.SliderView.js index b2129aa..e1a66eb 100644 --- a/modules/ext.RevisionSlider.SliderView.js +++ b/modules/ext.RevisionSlider.SliderView.js @@ -1,4 +1,10 @@ ( function ( mw, $ ) { + /** + * Module handling the view logic of the RevisionSlider slider + * + * @param {Slider} slider + * @constructor + */ var SliderView = function ( slider ) { this.slider = slider; this.diffPage = new mw.libs.revisionSlider.DiffPage( this.slider.getRevisions() ); @@ -246,14 +252,30 @@ this.diffPage.initOnPopState( this ); }, + /** + * Returns the pointer that points to the older revision + * + * @return {Pointer} + */ getOldRevPointer: function () { return this.pointerOlder.getPosition() <= this.pointerNewer.getPosition() ? this.pointerOlder : this.pointerNewer; }, + /** + * Returns the pointer that points to the newer revision + * + * @return {Pointer} + */ getNewRevPointer: function () { return this.pointerOlder.getPosition() > this.pointerNewer.getPosition() ? this.pointerOlder : this.pointerNewer; }, + /** + * Refreshes the diff page to show the diff for the specified revisions + * + * @param {number} revId1 + * @param {number} revId2 + */ refreshRevisions: function ( revId1, revId2 ) { var oldRev = Math.min( revId1, revId2 ), newRev = Math.max( revId1, revId2 ); @@ -261,18 +283,41 @@ this.diffPage.pushState( oldRev, newRev, this ); }, + /** + * @param {jQuery} $revs + * @param {number} pos + * @return {jQuery} + */ getRevElementAtPosition: function ( $revs, pos ) { return $revs.find( 'div.mw-revision[data-pos="' + pos + '"]' ); }, + /** + * Gets the jQuery element of the older selected revision + * + * @param {jQuery} $revs + * @return {jQuery} + */ getOldRevElement: function ( $revs ) { return $revs.find( 'div.mw-revision[data-revid="' + mw.config.values.extRevisionSliderOldRev + '"]' ); }, + /** + * Gets the jQuery element of the newer selected revision + * + * @param {jQuery} $revs + * @return {jQuery} + */ getNewRevElement: function ( $revs ) { return $revs.find( 'div.mw-revision[data-revid="' + mw.config.values.extRevisionSliderNewRev + '"]' ); }, + /** + * Initializes the Pointer objects based on the selected revisions + * + * @param {jQuery} $oldRevElement + * @param {jQuery} $newRevElement + */ initializePointers: function ( $oldRevElement, $newRevElement ) { if ( $oldRevElement.length === 0 || $newRevElement.length === 0 ) { // Note: this is currently caught in init.js @@ -283,6 +328,13 @@ this.resetPointerStylesBasedOnPosition(); }, + /** + * Adjusts the colors of the pointers without changing the upper/lower property based on values `p1` and `p2`. + * Used e.g. when pointers get dragged past one another. + * + * @param {number} p1 + * @param {number} p2 + */ resetPointerColorsBasedOnValues: function ( p1, p2 ) { if ( p1 > p2 ) { this.pointerOlder.getView().getElement().removeClass( 'mw-oldid-pointer' ).addClass( 'mw-newid-pointer' ); @@ -293,6 +345,9 @@ } }, + /** + * Resets the pointer styles (upper/lower, blue/yellow) based on their position. + */ resetPointerStylesBasedOnPosition: function () { this.getNewRevPointer().getView().getElement().removeClass( 'mw-oldid-pointer' ).addClass( 'mw-newid-pointer' ) .removeClass( 'mw-lower-pointer' ).addClass( 'mw-upper-pointer' ); @@ -300,6 +355,11 @@ .removeClass( 'mw-upper-pointer' ).addClass( 'mw-lower-pointer' ); }, + /** + * Highlights revisions between the pointers + * + * @param {jQuery} $revisions + */ resetRevisionStylesBasedOnPointerPosition: function ( $revisions ) { var olderRevPosition = this.getOldRevPointer().getPosition(), newerRevPosition = this.getNewRevPointer().getPosition(), @@ -316,10 +376,18 @@ } }, + /** + * Determines how many revisions fit onto the screen at once depending on the browser window width + * + * @return {number} + */ calculateRevisionsPerWindow: function () { return Math.floor( ( $( '#mw-content-text' ).width() - this.containerMargin ) / this.revisionWidth ); }, + /** + * @return {number} + */ calculateSliderContainerWidth: function () { return Math.min( this.slider.getRevisions().getLength(), this.calculateRevisionsPerWindow() ) * this.revisionWidth; }, @@ -362,7 +430,11 @@ this.alignPointers( duration ); }, - // Based on jQuery RTL Scroll Type Detector plugin by othree: https://github.com/othree/jquery.rtl-scroll-type + /** + * Based on jQuery RTL Scroll Type Detector plugin by othree: https://github.com/othree/jquery.rtl-scroll-type + * + * @return {string} - 'default', 'negative' or 'reverse' + */ determineRtlScrollType: function () { var $dummy = $( '<div>' ) .css( { @@ -386,6 +458,11 @@ return 'reverse'; }, + /** + * @param {jQuery} $element + * @param {number} scrollLeft + * @return {number} + */ getRtlScrollLeft: function ( $element, scrollLeft ) { if ( this.rtlScrollLeftType === 'reverse' ) { return scrollLeft; @@ -411,6 +488,12 @@ } ); }, + /** + * Returns the Pointer object that belongs to the passed element + * + * @param {jQuery} $e + * @return {Pointer} + */ whichPointer: function ( $e ) { return $e.attr( 'id' ) === 'mw-revslider-pointer-older' ? this.pointerOlder : this.pointerNewer; } diff --git a/modules/ext.RevisionSlider.fetchRevisions.js b/modules/ext.RevisionSlider.fetchRevisions.js index d07fc52..75cee53 100644 --- a/modules/ext.RevisionSlider.fetchRevisions.js +++ b/modules/ext.RevisionSlider.fetchRevisions.js @@ -4,7 +4,8 @@ /** * Fetches up to 500 revisions at a time * - * @param {{}} options - Options containing success /error callback, pageName and startId + * @param {Object} options - Options containing callbacks for `success` and `error` as well as fields for + * `pageName` and `startId` */ mw.libs.revisionSlider.fetchRevisions = function ( options ) { $.ajax( { -- To view, visit https://gerrit.wikimedia.org/r/294911 To unsubscribe, visit https://gerrit.wikimedia.org/r/settings Gerrit-MessageType: merged Gerrit-Change-Id: Ice393838545f1545ee085ecdcddfa35f60b32ecd Gerrit-PatchSet: 3 Gerrit-Project: mediawiki/extensions/RevisionSlider Gerrit-Branch: master Gerrit-Owner: Jakob <jakob.warkot...@wikimedia.de> Gerrit-Reviewer: Addshore <addshorew...@gmail.com> Gerrit-Reviewer: Jakob <jakob.warkot...@wikimedia.de> Gerrit-Reviewer: WMDE-Fisch <christoph.fisc...@wikimedia.de> Gerrit-Reviewer: WMDE-leszek <leszek.mani...@wikimedia.de> Gerrit-Reviewer: jenkins-bot <> _______________________________________________ MediaWiki-commits mailing list MediaWiki-commits@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits