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
