Krinkle has uploaded a new change for review. https://gerrit.wikimedia.org/r/54826
Change subject: Document and clean up events in all the things ...................................................................... Document and clean up events in all the things * Document them consistently between secetions Inheritance and Static Properties under their own (new) section Events. * Removed any quotes or brackets around the event name in existing @emit annotations Search: @emit.*[;"{}(){}] * For every call to this.emit() anywhere, added @emits. * Fixed all warnings for references to undefined events (introduced as a result of the previous point). Event handler parameter documented based on the emit() call and actual handlers using the event. Usually the latter is more elaborate. * Extend coverage of jQuery as needed (copied from mwcore/maintenance/jsduck/external.js written by me, hereby implicitly and explicitly released under MIT). Specifics * ve.ce.Surface#onContentChange: Fixed type of range from Object to ve.Range. * ve.ce.SurfaceObserver#poll: Fix syntax for code from {} to `backticks`. * ve.ui.Toolbar#onContextChange: Doesn't actually emit "clearState" event. Removed #onClearState in Tool, ButtonTool and DropdownTool. Bug: 45872 Change-Id: Id879aa769b2c72d86a0322e75dddeb868211ce28 --- M .docs/categories.json M .docs/external.js M CODING.md M modules/ve/ce/ve.ce.BranchNode.js M modules/ve/ce/ve.ce.Node.js M modules/ve/ce/ve.ce.Surface.js M modules/ve/ce/ve.ce.SurfaceObserver.js M modules/ve/dm/ve.dm.Node.js M modules/ve/dm/ve.dm.Surface.js M modules/ve/dm/ve.dm.SurfaceFragment.js M modules/ve/init/mw/ve.init.mw.Target.js M modules/ve/ui/layouts/ve.ui.GridLayout.js M modules/ve/ui/tools/ve.ui.AnnotationButtonTool.js M modules/ve/ui/tools/ve.ui.ButtonTool.js M modules/ve/ui/tools/ve.ui.DropdownTool.js M modules/ve/ui/ve.ui.Frame.js M modules/ve/ui/ve.ui.Tool.js M modules/ve/ui/ve.ui.Toolbar.js M modules/ve/ui/ve.ui.Window.js M modules/ve/ui/ve.ui.WindowSet.js M modules/ve/ui/widgets/ve.ui.ButtonWidget.js M modules/ve/ui/widgets/ve.ui.IconButtonWidget.js M modules/ve/ui/widgets/ve.ui.MenuItemWidget.js M modules/ve/ui/widgets/ve.ui.MenuWidget.js M modules/ve/ve.EventEmitter.js M modules/ve/ve.Node.js M modules/ve/ve.Registry.js 27 files changed, 256 insertions(+), 85 deletions(-) git pull ssh://gerrit.wikimedia.org:29418/mediawiki/extensions/VisualEditor refs/changes/26/54826/1 diff --git a/.docs/categories.json b/.docs/categories.json index 15ffd0e..5ec7775 100644 --- a/.docs/categories.json +++ b/.docs/categories.json @@ -154,7 +154,7 @@ "groups": [ { "name": "jQuery", - "classes": ["jQuery", "jQuery.Event", "QUnit"] + "classes": ["jQuery", "jQuery.Event", "jQuery.Promise", "jQuery.Deferred", "jQuery.jqXHR", "QUnit"] }, { "name": "JavaScript", diff --git a/.docs/external.js b/.docs/external.js index 9b3ee94..038f8e3 100644 --- a/.docs/external.js +++ b/.docs/external.js @@ -4,11 +4,31 @@ */ /** + * @method ajax + * @return {jqXHR} + */ + +/** * @class jQuery.Event * @source <http://api.jquery.com/category/events/event-object/> */ /** + * @class jQuery.Promise + */ + +/** + * @class jQuery.Deferred + * @mixins jQuery.Promise + */ + +/** + * @class jQuery.jqXHR + * @alternateClassName jqXHR + */ + + +/** * @class QUnit * @source <http://api.qunitjs.com/> */ diff --git a/CODING.md b/CODING.md index 649e478..5ed791c 100644 --- a/CODING.md +++ b/CODING.md @@ -59,7 +59,10 @@ * @source Text * @context {Type} Optional text. * @param {Type} name Optional text. +* @emits name * @returns {Type} Optional text. +* @chainable +* @throws {Type} ### Types diff --git a/modules/ve/ce/ve.ce.BranchNode.js b/modules/ve/ce/ve.ce.BranchNode.js index 2bc6c48..7838886 100644 --- a/modules/ve/ce/ve.ce.BranchNode.js +++ b/modules/ve/ce/ve.ce.BranchNode.js @@ -42,17 +42,19 @@ this.onSplice.apply( this, [0, 0].concat( model.getChildren() ) ); }; -/** - * @event rewrap - * @param {jQuery} $old - * @param {jQuery} $new - */ - /* Inheritance */ ve.inheritClass( ve.ce.BranchNode, ve.ce.Node ); ve.mixinClass( ve.ce.BranchNode, ve.BranchNode ); + +/* Events */ + +/** + * @event rewrap + * @param {jQuery} $old + * @param {jQuery} $new + */ /* Static Properties */ @@ -285,6 +287,7 @@ * * @method * @param {boolean} live New live state + * @emits live */ ve.ce.BranchNode.prototype.setLive = function ( live ) { this.live = live; diff --git a/modules/ve/ce/ve.ce.Node.js b/modules/ve/ce/ve.ce.Node.js index 6332f14..55fd1fb 100644 --- a/modules/ve/ce/ve.ce.Node.js +++ b/modules/ve/ce/ve.ce.Node.js @@ -41,6 +41,12 @@ ve.inheritClass( ve.ce.Node, ve.Node ); +/* Events */ + +/** + * @event live + */ + /* Static Members */ /** @@ -309,6 +315,7 @@ * * @method * @param {boolean} live The node has been attached to the live DOM (use false on detach) + * @emits live */ ve.ce.Node.prototype.setLive = function ( live ) { this.live = live; diff --git a/modules/ve/ce/ve.ce.Surface.js b/modules/ve/ce/ve.ce.Surface.js index b56fbae..48d9443 100644 --- a/modules/ve/ce/ve.ce.Surface.js +++ b/modules/ve/ce/ve.ce.Surface.js @@ -70,6 +70,16 @@ ve.inheritClass( ve.ce.Surface, ve.EventEmitter ); +/* Events */ + +/** + * @event selectionStart + */ + +/** + * @event selectionEnd + */ + /* Static Properties */ /** @@ -202,6 +212,7 @@ * * @method * @param {jQuery.Event} e Mouse up event + * @emits selectionEnd */ ve.ce.Surface.prototype.onDocumentMouseUp = function ( e ) { this.surfaceObserver.start(); @@ -217,6 +228,7 @@ * * @method * @param {jQuery.Event} e Mouse move event + * @emits selectionStart */ ve.ce.Surface.prototype.onDocumentMouseMove = function () { // Detect beginning of selection by moving mouse while dragging @@ -243,6 +255,7 @@ * * @method * @param {jQuery.Event} e Key down event + * @emits selectionStart */ ve.ce.Surface.prototype.onDocumentKeyDown = function ( e ) { if ( this.inIme === true ) { @@ -317,6 +330,7 @@ * * @method * @param {jQuery.Event} e Key up event + * @emits selectionEnd */ ve.ce.Surface.prototype.onDocumentKeyUp = function ( e ) { // Detect end of selecting by letting go of shift @@ -477,7 +491,7 @@ /** * Handle change events. * - * @see ve.dm.Surface#change + * @see ve.dm.Surface#method-change * * @method * @param {ve.dm.Transaction|null} transaction @@ -514,11 +528,11 @@ * @param {Object} previous Old data * @param {Object} previous.text Old plain text content * @param {Object} previous.hash Old DOM hash - * @param {Object} previous.range Old selection + * @param {ve.Range} previous.range Old selection * @param {Object} next New data * @param {Object} next.text New plain text content * @param {Object} next.hash New DOM hash - * @param {Object} next.range New selection + * @param {ve.Range} next.range New selection */ ve.ce.Surface.prototype.onContentChange = function ( node, previous, next ) { var data, range, len, annotations, offsetDiff, lengthDiff, sameLeadingAndTrailing, diff --git a/modules/ve/ce/ve.ce.SurfaceObserver.js b/modules/ve/ce/ve.ce.SurfaceObserver.js index 879f411..dd84229 100644 --- a/modules/ve/ce/ve.ce.SurfaceObserver.js +++ b/modules/ve/ce/ve.ce.SurfaceObserver.js @@ -33,6 +33,34 @@ ve.inheritClass( ve.ce.SurfaceObserver, ve.EventEmitter ); +/* Events */ + +/** + * When #poll sees a change this event is emitted (before the + * properties are updated). + * + * @event contentChange + * @param {HTMLElement} node DOM node the change occured in + * @param {Object} previous Old data + * @param {Object} previous.text Old plain text content + * @param {Object} previous.hash Old DOM hash + * @param {ve.Range} previous.range Old selection + * @param {Object} next New data + * @param {Object} next.text New plain text content + * @param {Object} next.hash New DOM hash + * @param {ve.Range} next.range New selection + */ + +/** + * When #poll observes a change in the document and the new + * selection does not equal as the last known selection, this event + * is emitted (before the properties are updated). + * + * @event selectionChange + * @param {ve.Range} oldRange + * @param {ve.Range} newRange + */ + /* Methods */ /** @@ -85,12 +113,14 @@ /** * Poll for changes. * - * If {async} is false or undefined then polling will occcur asynchronously. + * If `async` is false or undefined then polling will occcur asynchronously. * * TODO: fixing selection in certain cases, handling selection across multiple nodes in Firefox * * @method * @param {boolean} async Poll asynchronously + * @emits contentChange + * @emits selectionChange */ ve.ce.SurfaceObserver.prototype.poll = function ( async ) { var delayPoll, $branch, node, text, hash, range, rangyRange; diff --git a/modules/ve/dm/ve.dm.Node.js b/modules/ve/dm/ve.dm.Node.js index c392e00..25ce142 100644 --- a/modules/ve/dm/ve.dm.Node.js +++ b/modules/ve/dm/ve.dm.Node.js @@ -466,7 +466,7 @@ * @method * @param {number} adjustment Amount to adjust length by * @throws {Error} Invalid adjustment error if resulting length is less than 0 - * @emits lengthChange (diff) + * @emits lengthChange * @emits update */ ve.dm.Node.prototype.adjustLength = function ( adjustment ) { diff --git a/modules/ve/dm/ve.dm.Surface.js b/modules/ve/dm/ve.dm.Surface.js index 5de3c73..801a468 100644 --- a/modules/ve/dm/ve.dm.Surface.js +++ b/modules/ve/dm/ve.dm.Surface.js @@ -33,6 +33,41 @@ ve.inheritClass( ve.dm.Surface, ve.EventEmitter ); +/* Events */ + +/** + * @event lock + */ + +/** + * @event unlock + */ + +/** + * @event select + * @param {ve.ui.MenuItemWidget} item Menu item. + */ + +/** + * @event transact + * @param {ve.dm.Transaction[]} transactions Transactions that have just been processed. + */ + +/** + * @event contextChange + */ + +/** + * @event change + * @see #method-change + * @param {ve.dm.Transaction|null} transaction + * @param {ve.Range|undefined} selection + */ + +/** + * @event history + */ + /* Methods */ /** @@ -123,7 +158,7 @@ * * @method * @param {ve.AnnotationSet|null} Insertion anotations to use or null to disable them - * @emits 'contextChange' + * @emits contextChange */ ve.dm.Surface.prototype.setInsertionAnnotations = function ( annotations ) { if ( !this.enabled ) { @@ -138,7 +173,7 @@ * * @method * @param {ve.AnnotationSet} Insertion anotation to add - * @emits 'contextChange' + * @emits contextChange */ ve.dm.Surface.prototype.addInsertionAnnotation = function ( annotation ) { if ( !this.enabled ) { @@ -153,7 +188,7 @@ * * @method * @param {ve.AnnotationSet} Insertion anotation to remove - * @emits 'contextChange' + * @emits contextChange */ ve.dm.Surface.prototype.removeInsertionAnnotation = function ( annotation ) { if ( !this.enabled ) { @@ -221,6 +256,12 @@ * @param {ve.dm.Transaction|ve.dm.Transaction[]|null} transactions One or more transactions to * process, or null to process none * @param {ve.Range|undefined} selection + * @emits lock + * @emits select + * @emits transact + * @emits contextChange + * @emits change + * @emits unlock */ ve.dm.Surface.prototype.change = function ( transactions, selection ) { if ( !this.enabled ) { @@ -327,6 +368,7 @@ * * @method * @param {ve.Range} selection New selection range + * @emits history */ ve.dm.Surface.prototype.breakpoint = function ( selection ) { if ( !this.enabled ) { @@ -346,7 +388,11 @@ * Step backwards in history. * * @method + * @see ve.dm.Document#rollback * @returns {ve.Range} Selection or null if no further state could be reached + * @emits lock + * @emits unlock + * @emits history */ ve.dm.Surface.prototype.undo = function () { if ( !this.enabled ) { @@ -377,7 +423,11 @@ * Step forwards in history. * * @method + * @see ve.dm.Document#commit * @returns {ve.Range} Selection or null if no further state could be reached + * @emits lock + * @emits unlock + * @emits history */ ve.dm.Surface.prototype.redo = function () { if ( !this.enabled ) { diff --git a/modules/ve/dm/ve.dm.SurfaceFragment.js b/modules/ve/dm/ve.dm.SurfaceFragment.js index 87ada3f..c449828 100644 --- a/modules/ve/dm/ve.dm.SurfaceFragment.js +++ b/modules/ve/dm/ve.dm.SurfaceFragment.js @@ -10,9 +10,9 @@ * * @class * @constructor - * @param {ve.dm.Surface} surface Target surface - * @param {ve.Range} [range] Range within target document, current selection used by default - * @param {boolean} [noAutoSelect] Update the surface's selection when making changes + * @param {ve.dm.Surface} surface Target surface. + * @param {ve.Range} [range] Range within target document, current selection used by default. + * @param {boolean} [noAutoSelect] Update the surface's selection when making changes. */ ve.dm.SurfaceFragment = function VeDmSurfaceFragment( surface, range, noAutoSelect ) { // Short-circuit for missing-surface null fragment @@ -59,7 +59,7 @@ * This keeps the range of the fragment valid, even while other transactions are being processed. * * @method - * @param {ve.dm.Transaction[]} txs Transactions that have just been processed + * @param {ve.dm.Transaction[]} txs Transactions that have just been processed. */ ve.dm.SurfaceFragment.prototype.onTransact = function ( txs ) { for ( var i = 0; i < txs.length; i++ ) { diff --git a/modules/ve/init/mw/ve.init.mw.Target.js b/modules/ve/init/mw/ve.init.mw.Target.js index caeef3d..6c098a5 100644 --- a/modules/ve/init/mw/ve.init.mw.Target.js +++ b/modules/ve/init/mw/ve.init.mw.Target.js @@ -52,22 +52,49 @@ /** * @event load + * @param {HTMLDocument} dom + */ + +/** + * @event editConflict */ /** * @event save + * @param {string} html + */ + +/** + * @event showChanges + * @param {string} diff */ /** * @event loadError + * @param {jqXHR|null} jqXHR + * @param {string} status Text status message + * @param {Mixed|null} error HTTP status text */ /** * @event saveError + * @param {jqXHR|null} jqXHR + * @param {string} status Text status message + * @param {Mixed|null} error HTTP status text */ /** * @event showChangesError + * @param {jqXHR|null} jqXHR + * @param {string} status Text status message + * @param {Mixed|null} error HTTP status text + */ + +/** + * @event serializeError + * @param {jqXHR|null} jqXHR + * @param {string} status Text status message + * @param {Mixed|null} error HTTP status text */ /* Inheritance */ @@ -87,7 +114,7 @@ * @method * @param {Object} response XHR Response object * @param {string} status Text status message - * @emits loadError (null, message, null) + * @emits loadError */ ve.init.mw.Target.onLoad = function ( response ) { var key, tmp, el, html, @@ -162,7 +189,7 @@ * * @static * @method - * @emits load (dom) + * @emits load */ ve.init.mw.Target.onReady = function () { this.loading = false; @@ -181,7 +208,7 @@ * @param {Object} jqXHR * @param {string} status Text status message * @param {Mixed} error HTTP status text - * @emits loadError (jqXHR, status, error) + * @emits loadError */ ve.init.mw.Target.onLoadError = function ( jqXHR, status, error ) { this.loading = false; @@ -197,8 +224,8 @@ * @method * @param {Object} response Response data * @param {string} status Text status message - * @emits save (html) - * @emits saveError (null, message, null) + * @emits editConflict + * @emits save */ ve.init.mw.Target.onSave = function ( response ) { this.saving = false; @@ -233,7 +260,7 @@ * @param {Object} jqXHR * @param {string} status Text status message * @param {Mixed} error HTTP status text - * @emits saveError (jqXHR, status, error) + * @emits saveError */ ve.init.mw.Target.onSaveError = function ( jqXHR, status, error ) { this.saving = false; @@ -246,10 +273,9 @@ * * @static * @method - * @param {Object} response Response data - * @param {string} status Text status message - * @emits save (diffHtml) - * @emits saveError (null, message, null) + * @param {Object} response API response data. + * @param {string} status Text status message. + * @emits showChanges */ ve.init.mw.Target.onShowChanges = function ( response ) { var data = response.visualeditor; @@ -279,7 +305,7 @@ * @param {Object} jqXHR * @param {string} status Text status message * @param {Mixed} error HTTP status text - * @emits showChangesError (jqXHR, status, error) + * @emits showChangesError */ ve.init.mw.Target.onShowChangesError = function ( jqXHR, status, error ) { this.saving = false; @@ -293,10 +319,8 @@ * * @static * @method - * @param {Object} response XHR Response object + * @param {Object} data API response data * @param {string} status Text status message - * @emits save (html) - * @emits saveError (null, message, null) */ ve.init.mw.Target.onSerialize = function ( response ) { this.serializing = false; @@ -324,14 +348,14 @@ * * @static * @method - * @param {Object} data HTTP Response object + * @param {jqXHR|null} jqXHR * @param {string} status Text status message - * @param {Mixed} error Thrown exception or HTTP error string - * @emits saveError (response, status, error) + * @param {Mixed|null} error HTTP status text + * @emits serializeError */ -ve.init.mw.Target.onSerializeError = function ( response, status, error ) { +ve.init.mw.Target.onSerializeError = function ( jqXHR, status, error ) { this.serializing = false; - this.emit( 'serializeError', response, status, error ); + this.emit( 'serializeError', jqXHR, status, error ); }; /* Methods */ diff --git a/modules/ve/ui/layouts/ve.ui.GridLayout.js b/modules/ve/ui/layouts/ve.ui.GridLayout.js index d2acd70..aae4bad 100644 --- a/modules/ve/ui/layouts/ve.ui.GridLayout.js +++ b/modules/ve/ui/layouts/ve.ui.GridLayout.js @@ -75,7 +75,8 @@ * @method * @param {number[]} widths Widths of columns as ratios * @param {number[]} heights Heights of rows as ratios - * @throws {Error} If grid is not large enough to fit all panels + * @throws {Error} If grid is not large enough to fit all panels. + * @emits layout */ ve.ui.GridLayout.prototype.layout = function ( widths, heights ) { var x, y, @@ -114,6 +115,7 @@ * Update panel positions and sizes. * * @method + * @emits update */ ve.ui.GridLayout.prototype.update = function () { var x, y, panel, diff --git a/modules/ve/ui/tools/ve.ui.AnnotationButtonTool.js b/modules/ve/ui/tools/ve.ui.AnnotationButtonTool.js index b7e2e70..b039d13 100644 --- a/modules/ve/ui/tools/ve.ui.AnnotationButtonTool.js +++ b/modules/ve/ui/tools/ve.ui.AnnotationButtonTool.js @@ -55,9 +55,9 @@ * Handle the toolbar state being updated. * * @method - * @param {ve.dm.Node[]} nodes List of nodes covered by the current selection - * @param {ve.AnnotationSet} full Annotations that cover all of the current selection - * @param {ve.AnnotationSet} partial Annotations that cover some or all of the current selection + * @param {ve.dm.Node[]} nodes List of nodes covered by the current selection. + * @param {ve.AnnotationSet} full Annotations that cover all of the current selection. + * @param {ve.AnnotationSet} partial Annotations that cover some or all of the current selection. */ ve.ui.AnnotationButtonTool.prototype.onUpdateState = function ( nodes, full ) { this.setActive( full.hasAnnotationWithName( this.constructor.static.annotation.name ) ); diff --git a/modules/ve/ui/tools/ve.ui.ButtonTool.js b/modules/ve/ui/tools/ve.ui.ButtonTool.js index a575dd6..9449a2e 100644 --- a/modules/ve/ui/tools/ve.ui.ButtonTool.js +++ b/modules/ve/ui/tools/ve.ui.ButtonTool.js @@ -112,15 +112,6 @@ }; /** - * Handle the toolbar state being cleared. - * - * @method - */ -ve.ui.ButtonTool.prototype.onClearState = function () { - this.setActive( false ); -}; - -/** * Check if the button is active. * * @method diff --git a/modules/ve/ui/tools/ve.ui.DropdownTool.js b/modules/ve/ui/tools/ve.ui.DropdownTool.js index b68d2c9..2bb2275 100644 --- a/modules/ve/ui/tools/ve.ui.DropdownTool.js +++ b/modules/ve/ui/tools/ve.ui.DropdownTool.js @@ -131,15 +131,6 @@ }; /** - * Handle toolbar state being cleared. - * - * @method - */ -ve.ui.DropdownTool.prototype.onClearState = function () { - this.setLabel(); -}; - -/** * Set the label. * * If the label value is empty, undefined or only contains whitespace an empty label will be used. diff --git a/modules/ve/ui/ve.ui.Frame.js b/modules/ve/ui/ve.ui.Frame.js index 706f71d..471b030 100644 --- a/modules/ve/ui/ve.ui.Frame.js +++ b/modules/ve/ui/ve.ui.Frame.js @@ -45,6 +45,9 @@ /* Methods */ +/** + * @emits initialize + */ ve.ui.Frame.prototype.onLoad = function () { var i, len, doc, $head, promises = [], @@ -79,7 +82,7 @@ }; /** - * + * @param {Function} callback */ ve.ui.Frame.prototype.run = function ( callback ) { if ( this.initialized ) { diff --git a/modules/ve/ui/ve.ui.Tool.js b/modules/ve/ui/ve.ui.Tool.js index b3fc113..a0fc42c 100644 --- a/modules/ve/ui/ve.ui.Tool.js +++ b/modules/ve/ui/ve.ui.Tool.js @@ -25,7 +25,7 @@ // Events this.toolbar.addListenerMethods( - this, { 'updateState': 'onUpdateState', 'clearState': 'onClearState' } + this, { 'updateState': 'onUpdateState' } ); ve.triggerRegistry.addListenerMethods( this, { 'register': 'onTriggerRegistryRegister' } @@ -101,20 +101,6 @@ ve.ui.Tool.prototype.onUpdateState = function () { throw new Error( 've.ui.Tool.onUpdateState not implemented in this subclass:' + this.constructor - ); -}; - -/** - * Handle the toolbar state being cleared. - * - * This is an abstract method that must be overridden in a concrete subclass. - * - * @abstract - * @method - */ -ve.ui.Tool.prototype.onClearState = function () { - throw new Error( - 've.ui.Tool.onClearState not implemented in this subclass:' + this.constructor ); }; diff --git a/modules/ve/ui/ve.ui.Toolbar.js b/modules/ve/ui/ve.ui.Toolbar.js index de0be26..617b2a6 100644 --- a/modules/ve/ui/ve.ui.Toolbar.js +++ b/modules/ve/ui/ve.ui.Toolbar.js @@ -38,13 +38,24 @@ ve.inheritClass( ve.ui.Toolbar, ve.EventEmitter ); +/* Events */ + +/** + * @event updateState + * @see ve.dm.SurfaceFragment#getAnnotations + * @param {ve.dm.Node[]} nodes List of nodes covered by the current selection. + * @param {ve.AnnotationSet} full Annotations that cover all of the current selection. + * @param {ve.AnnotationSet} partial Annotations that cover some or all of the current selection. + */ + + /* Methods */ /** * Gets the surface the toolbar controls. * * @method - * @returns {ve.Surface} Surface being controlled + * @returns {ve.Surface} Surface being controlled. */ ve.ui.Toolbar.prototype.getSurface = function () { return this.surface; @@ -54,8 +65,7 @@ * Handle context changes on the surface. * * @method - * @emits "updateState" (nodes, full, partial) - * @emits "clearState" + * @emits updateState */ ve.ui.Toolbar.prototype.onContextChange = function () { var i, len, leafNodes, diff --git a/modules/ve/ui/ve.ui.Window.js b/modules/ve/ui/ve.ui.Window.js index 99a9880..088efcd 100644 --- a/modules/ve/ui/ve.ui.Window.js +++ b/modules/ve/ui/ve.ui.Window.js @@ -14,6 +14,7 @@ * * @constructor * @param {ve.Surface} surface + * @emits initialize */ ve.ui.Window = function VeUiWindow( surface ) { // Inheritance @@ -51,16 +52,23 @@ /* Events */ /** + * @event initialize + */ + +/** * @event setup + * @param {ve.ui.Window} win Window that's been setup. */ /** * @event open + * @param {ve.ui.Window} win Window that's been opened. */ /** * @event close - * @param {Boolean} accept Changes have been accepted + * @param {ve.ui.Window} win Window that's been closed. + * @param {boolean} accept Changes have been accepted. */ /* Static Properties */ @@ -257,6 +265,7 @@ * loop. * * @method + * @param {boolean} accept Changes have been accepted * @emits close */ ve.ui.Window.prototype.close = function ( remove ) { diff --git a/modules/ve/ui/ve.ui.WindowSet.js b/modules/ve/ui/ve.ui.WindowSet.js index c3461ac..8fd94e0 100644 --- a/modules/ve/ui/ve.ui.WindowSet.js +++ b/modules/ve/ui/ve.ui.WindowSet.js @@ -37,18 +37,18 @@ /** * @event setup - * @param {ve.ui.Window} win Window that's been setup + * @param {ve.ui.Window} win Window that's been setup. */ /** * @event open - * @param {ve.ui.Window} win Window that's been opened + * @param {ve.ui.Window} win Window that's been opened. */ /** * @event close - * @param {ve.ui.Window} win Window that's been closed - * @param {boolean} accept Changes have been accepted + * @param {ve.ui.Window} win Window that's been closed. + * @param {boolean} accept Changes have been accepted. */ /* Methods */ @@ -58,6 +58,7 @@ * * @method * @param {ve.ui.Window} win Window that's been setup + * @emits setup */ ve.ui.WindowSet.prototype.onWindowSetup = function ( win ) { this.emit( 'setup', win ); @@ -68,6 +69,7 @@ * * @method * @param {ve.ui.Window} win Window that's been opened + * @emits open */ ve.ui.WindowSet.prototype.onWindowOpen = function ( win ) { this.currentWindow = win; @@ -80,6 +82,7 @@ * @method * @param {ve.ui.Window} win Window that's been opened * @param {boolean} accept Changes have been accepted + * @emits close */ ve.ui.WindowSet.prototype.onWindowClose = function ( win, accept ) { this.currentWindow = null; diff --git a/modules/ve/ui/widgets/ve.ui.ButtonWidget.js b/modules/ve/ui/widgets/ve.ui.ButtonWidget.js index 8da031e..be853c3 100644 --- a/modules/ve/ui/widgets/ve.ui.ButtonWidget.js +++ b/modules/ve/ui/widgets/ve.ui.ButtonWidget.js @@ -57,6 +57,7 @@ * * @method * @param {jQuery.Event} e Mouse click event + * @emits click */ ve.ui.ButtonWidget.prototype.onClick = function () { if ( !this.disabled ) { diff --git a/modules/ve/ui/widgets/ve.ui.IconButtonWidget.js b/modules/ve/ui/widgets/ve.ui.IconButtonWidget.js index e77fa7d..eadce93 100644 --- a/modules/ve/ui/widgets/ve.ui.IconButtonWidget.js +++ b/modules/ve/ui/widgets/ve.ui.IconButtonWidget.js @@ -54,6 +54,7 @@ * * @method * @param {jQuery.Event} e Mouse click event + * @emits click */ ve.ui.IconButtonWidget.prototype.onClick = function () { if ( !this.disabled ) { diff --git a/modules/ve/ui/widgets/ve.ui.MenuItemWidget.js b/modules/ve/ui/widgets/ve.ui.MenuItemWidget.js index 21f67c5..cb2ab18 100644 --- a/modules/ve/ui/widgets/ve.ui.MenuItemWidget.js +++ b/modules/ve/ui/widgets/ve.ui.MenuItemWidget.js @@ -178,6 +178,7 @@ * * @method * @param {boolean} [state=false] Highlight item + * @emits highlight * @chainable */ ve.ui.MenuItemWidget.prototype.setHighlighted = function ( state ) { @@ -197,6 +198,7 @@ * @method * @param {boolean} [state=false] Select item * @param {boolean} [silent=false] Update UI only, do not emit select event + * @emits select * @chainable */ ve.ui.MenuItemWidget.prototype.setSelected = function ( state, silent ) { diff --git a/modules/ve/ui/widgets/ve.ui.MenuWidget.js b/modules/ve/ui/widgets/ve.ui.MenuWidget.js index 89dcf46..592db20 100644 --- a/modules/ve/ui/widgets/ve.ui.MenuWidget.js +++ b/modules/ve/ui/widgets/ve.ui.MenuWidget.js @@ -92,6 +92,7 @@ * @method * @private * @param {ve.ui.MenuItemWidget} item Selected item + * @emits select */ ve.ui.MenuWidget.prototype.onItemSelect = function ( item ) { var hash; diff --git a/modules/ve/ve.EventEmitter.js b/modules/ve/ve.EventEmitter.js index 1061f41..26df133 100644 --- a/modules/ve/ve.EventEmitter.js +++ b/modules/ve/ve.EventEmitter.js @@ -17,6 +17,15 @@ this.events = {}; }; +/* Events */ + +/** + * @event newListener + * @see #addListener + * @param {string} type Name of the event. + * @param {Function} listener Callback to invoke when event occurs. + */ + /* Methods */ /** @@ -51,6 +60,7 @@ * @param {string} type Type of event to listen to * @param {Function} listener Listener to call when event occurs * @chainable + * @emits newListener * @throws {Error} Listener argument is not a function */ ve.EventEmitter.prototype.addListener = function ( type, listener ) { diff --git a/modules/ve/ve.Node.js b/modules/ve/ve.Node.js index 9385ce0..b1f9156 100644 --- a/modules/ve/ve.Node.js +++ b/modules/ve/ve.Node.js @@ -26,11 +26,12 @@ /** * @event attach - * @param parent + * @param {ve.Node} parent */ /** * @event detach + * @param {ve.Node} parent */ /* Inheritance */ diff --git a/modules/ve/ve.Registry.js b/modules/ve/ve.Registry.js index 1518689..394ee84 100644 --- a/modules/ve/ve.Registry.js +++ b/modules/ve/ve.Registry.js @@ -24,6 +24,14 @@ ve.inheritClass( ve.Registry, ve.EventEmitter ); +/* Events */ + +/** + * @event register + * @param {string} name + * @param {Mixed} data + */ + /* Methods */ /** @@ -32,6 +40,7 @@ * @method * @param {string|string[]} name Symbolic name or list of symbolic names * @param {Mixed} data Data to associate with symbolic name + * @emits register * @throws {Error} Name argument must be a string or array */ ve.Registry.prototype.register = function ( name, data ) { -- To view, visit https://gerrit.wikimedia.org/r/54826 To unsubscribe, visit https://gerrit.wikimedia.org/r/settings Gerrit-MessageType: newchange Gerrit-Change-Id: Id879aa769b2c72d86a0322e75dddeb868211ce28 Gerrit-PatchSet: 1 Gerrit-Project: mediawiki/extensions/VisualEditor Gerrit-Branch: master Gerrit-Owner: Krinkle <ttij...@wikimedia.org> _______________________________________________ MediaWiki-commits mailing list MediaWiki-commits@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits