JSDoc: Fix complex return types

Change-Id: I4578d600bffef78a338b28aec8ec152cdb658c39

src/ce/ve.ce.BranchNode.js

@@ -414,9 +414,7 @@ ve.ce.BranchNode.prototype.detach = function () {
  * The node/offset have the same semantics as a DOM Selection focusNode/focusOffset
  *
  * @param {number} offset The offset inside this node of the required position
- * @return {Object|null} The DOM position
- * @return {Node} return.node DOM node; guaranteed to be this node's final DOM node
- * @return {number} return.offset DOM offset
+ * @return {ve.ce.NodeAndOffset} The DOM position; guaranteed to be this node's final DOM node
  */
 ve.ce.BranchNode.prototype.getDomPosition = function ( offset ) {
 	var domNode = this.$element.last()[ 0 ];

src/ce/ve.ce.ContentBranchNode.js

@@ -196,6 +196,20 @@ ve.ce.ContentBranchNode.prototype.setupInlineSlugs = function () {
 	ve.ce.ContentBranchNode.super.prototype.setupInlineSlugs.apply( this, arguments );
 };
 
+/**
+ * @typedef {Object} UnicornInfo
+ * @memberof ve.ce.ContentBranchNode
+ * @property {boolean} hasCursor
+ * @property {ve.dm.AnnotationSet|null} annotations
+ * @property {HTMLElement[]|null} unicorns
+ */
+
+/**
+ * @typedef {HTMLElement} HTMLElementWithUnicorn
+ * @memberof ve.ce.ContentBranchNode
+ * @property {ve.ce.ContentBranchNode.UnicornInfo} unicornInfo Unicorn information
+ */
+
 /**
  * Get an HTML rendering of the contents.
  *
@@ -203,8 +217,7 @@ ve.ce.ContentBranchNode.prototype.setupInlineSlugs = function () {
  * do this with #appendRenderedContents, which resolves the cloned
  * nodes returned by this function back to their originals.
  *
- * @return {HTMLElement} Wrapper containing rendered contents
- * @return {Object} return.unicornInfo Unicorn information
+ * @return {ve.ce.ContentBranchNode.HTMLElementWithUnicorn} Wrapper containing rendered contents
  */
 ve.ce.ContentBranchNode.prototype.getRenderedContents = function () {
 	var annotationsChanged,

src/ce/ve.ce.Document.js

@@ -100,9 +100,7 @@ ve.ce.Document.prototype.getSlugAtOffset = function ( offset ) {
  *
  * @private
  * @param {number} offset Linear model offset
- * @return {Object} position
- * @return {Node} return.node position node
- * @return {number} return.offset position offset within the node
+ * @return {ve.ce.NodeAndOffset} Position
  * @throws {Error} Offset could not be translated to a DOM element and offset
  */
 ve.ce.Document.prototype.getNodeAndOffset = function ( offset ) {

src/ce/ve.ce.Surface.js

@@ -2287,7 +2287,7 @@ ve.ce.Surface.prototype.getBeforePasteAnnotationSet = function () {
  * Handle native paste event
  *
  * @param {jQuery.Event} e Paste event
- * @return {boolean} False if the event is cancelled
+ * @return {boolean|undefined} False if the event is cancelled
  */
 ve.ce.Surface.prototype.onPaste = function ( e ) {
 	var surface = this;
@@ -2545,13 +2545,18 @@ ve.ce.Surface.prototype.afterPaste = function () {
 	} );
 };
 
+/**
+ * @typedef {Object} ClipboardData
+ * @memberof ve.ce
+ * @property {string|undefined} clipboardKey Clipboard key, if present
+ * @property {jQuery|undefined} $clipboardHtml Clipboard html, if used to extract the clipboard key
+ * @property {ve.dm.DocumentSlice|undefined} slice Relevant slice of this document, if the key points to it
+ */
+
 /**
  * Extract the clipboard key and other relevant data from beforePasteData / the paste target
  *
- * @return {Object} Data
- * @return {string|undefined} return.clipboardKey Clipboard key, if present
- * @return {jQuery|undefined} return.$clipboardHtml Clipboard html, if used to extract the clipboard key
- * @return {ve.dm.DocumentSlice|undefined} return.slice Relevant slice of this document, if the key points to it
+ * @return {ve.ce.ClipboardData} Data
  */
 ve.ce.Surface.prototype.afterPasteExtractClipboardData = function () {
 	var clipboardKey, clipboardHash, $clipboardHtml,
@@ -4012,6 +4017,7 @@ ve.ce.Surface.prototype.fixupCursorPosition = function ( direction, extend ) {
  *
  * @param {boolean} [isPaste] Whether this in the context of a paste
  * @param {boolean} [isDelete] Whether this is after content being deleted
+ * @return {ve.ui.SequenceRegistry.Match[]}
  */
 ve.ce.Surface.prototype.findMatchingSequences = function ( isPaste, isDelete ) {
 	var selection = this.getSelection();
@@ -4081,6 +4087,11 @@ ve.ce.Surface.prototype.findAndExecuteDelayedSequences = function () {
 // Deprecated alias
 ve.ce.Surface.prototype.checkDelayedSequences = ve.ce.Surface.prototype.findAndExecuteDelayedSequences;
 
+/**
+ * Execute matched sequences
+ *
+ * @param {ve.ui.SequenceRegistry.Match[]} sequences
+ */
 ve.ce.Surface.prototype.executeSequences = function ( sequences ) {
 	var executed = false;
 
@@ -5111,12 +5122,6 @@ ve.ce.Surface.prototype.annotationsAtNode = function ( node, filter ) {
  *
  * @param {ve.Range|null} range Range to get selection for
  * @return {ve.SelectionState} The selection
- * @return {Node|null} return.anchorNode The anchor node
- * @return {number} return.anchorOffset The anchor offset
- * @return {Node|null} return.focusNode The focus node
- * @return {number} return.focusOffset The focus offset
- * @return {boolean} return.isCollapsed True if the focus and anchor are in the same place
- * @return {boolean} return.isBackwards True if the focus is before the anchor
  */
 ve.ce.Surface.prototype.getSelectionState = function ( range ) {
 	var dmDoc = this.getModel().getDocument();

src/ce/ve.ce.js

@@ -111,13 +111,17 @@ ve.ce.getDomHash = function ( element ) {
 	return hash;
 };
 
+/**
+ * @typedef {Object} NodeAndOffset
+ * @memberof ve.ce
+ * @return {Node} node
+ * @return {number} offset
+ */
 /**
  * Get the first cursor offset immediately after a node.
  *
  * @param {Node} node DOM node
- * @return {Object}
- * @return {Node} return.node
- * @return {number} return.offset
+ * @return {ve.ce.NodeAndOffset}
  */
 ve.ce.nextCursorOffset = function ( node ) {
 	var nextNode, offset;
@@ -135,9 +139,7 @@ ve.ce.nextCursorOffset = function ( node ) {
  * Get the first cursor offset immediately before a node.
  *
  * @param {Node} node DOM node
- * @return {Object}
- * @return {Node} return.node
- * @return {number} return.offset
+ * @return {ve.ce.NodeAndOffset}
  */
 ve.ce.previousCursorOffset = function ( node ) {
 	var previousNode, offset;

src/dm/ve.dm.Change.js

@@ -288,6 +288,14 @@ ve.dm.Change.static.rebaseTransactions = function ( transactionA, transactionB )
 	return [ transactionA, transactionB ];
 };
 
+/**
+ * @typedef {Object} RebasedChange
+ * @memberof ve.dm.Change
+ * @property {ve.dm.Change} rebased Rebase onto history of uncommitted (or an initial segment of it)
+ * @property {ve.dm.Change} transposedHistory Rebase of history onto initial segment of uncommitted
+ * @property {ve.dm.Change|null} rejected Unrebasable final segment of uncommitted
+ */
+
 /**
  * Rebase a change on top of a parallel committed one
  *
@@ -351,10 +359,7 @@ ve.dm.Change.static.rebaseTransactions = function ( transactionA, transactionB )
  *
  * @param {ve.dm.Change} history Committed history
  * @param {ve.dm.Change} uncommitted New transactions, with same start as history
- * @return {Object} Rebased
- * @return {ve.dm.Change} return.rebased Rebase onto history of uncommitted (or an initial segment of it)
- * @return {ve.dm.Change} return.transposedHistory Rebase of history onto initial segment of uncommitted
- * @return {ve.dm.Change|null} return.rejected Unrebasable final segment of uncommitted
+ * @return {ve.dm.Change.RebasedChange}
  */
 ve.dm.Change.static.rebaseUncommittedChange = function ( history, uncommitted ) {
 	if ( history.start !== uncommitted.start ) {
@@ -450,21 +455,31 @@ ve.dm.Change.static.rebaseUncommittedChange = function ( history, uncommitted )
 	};
 };
 
+/**
+ * @typedef UniformTextInfo
+ * @memberof ve.dm.Change
+ * @property {string} text The code units, in a single string
+ * @property {string} annotations Annotation hashes for all text
+ * @property {string} annotationString Comma-separated annotation hashes
+ */
+
+/**
+ * @typedef TransactionInfo
+ * @memberof ve.dm.Change
+ * @property {number} start The start offset of the replacement
+ * @property {number} end The end offset of the replacement (after replacement)
+ * @property {number} docLength The total length of the document (after replacement)
+ * @property {number} authorId The author ID
+ * @property {ve.dm.Change.UniformTextInfo|null} uniformInsert The insertion as uniform text, or null if not
+ */
+
 /**
  * Get info about a transaction if it is a "simple replacement", or null if not
  *
  * A simple replacement transaction is one that has just one retain op
  *
  * @param {ve.dm.Transaction} tx The transaction
- * @return {Object|null} Info about the transaction if a simple replacement, else null
- * @return {number} return.start The start offset of the replacement
- * @return {number} return.end The end offset of the replacement (after replacement)
- * @return {number} return.docLength The total length of the document (after replacement)
- * @return {number} return.authorId The author ID
- * @return {Object|null} return.uniformInsert The insertion as uniform text, or null if not
- * @return {string} return.uniformInsert.text The plain text of the uniform text
- * @return {string} return.uniformInsert.annotations Annotation hashes for all text
- * @return {string} return.uniformInsert.annotationString Comma-separated annotation hashes
+ * @return {ve.dm.Change.TransactionInfo|null} Info about the transaction if a simple replacement, else null
  */
 ve.dm.Change.static.getTransactionInfo = function ( tx ) {
 	// Copy of ve.dm.ElementLinearData.static.getAnnotationHashesFromItem, but we
@@ -504,10 +519,7 @@ ve.dm.Change.static.getTransactionInfo = function ( tx ) {
 	 * every item is a single code unit of text
 	 *
 	 * @param {Array} items The items
-	 * @return {Object|null} Info about the uniform text, or null if not uniform text
-	 * @return {string} return.text The code units, in a single string
-	 * @return {string} return.annotations Annotation hashes for all text
-	 * @return {string} return.annotationString Comma-separated annotation hashes
+	 * @return {ve.dm.Change.UniformTextInfo|null} Info about the uniform text, or null if not uniform text
 	 */
 	function getUniformText( items ) {
 		var codeUnits = [];

src/dm/ve.dm.Document.js

@@ -1223,6 +1223,16 @@ ve.dm.Document.prototype.getNodesByType = function ( type, sort ) {
 	return nodes;
 };
 
+/**
+ * @typedef FixedInsertion
+ * @memberof ve.dm.Document
+ * @property {Array} data Possibly modified copy of `data`
+ * @property {number} offset Possibly modified offset
+ * @property {number} remove Number of elements to remove after the modified `offset`
+ * @property {number} [insertedDataOffset] Offset of intended insertion within fixed up data
+ * @property {number} [insertedDataLength] Length of intended insertion within fixed up data
+ */
+
 /**
  * Fix up data so it can safely be inserted into the document data at an offset.
  *
@@ -1230,12 +1240,7 @@ ve.dm.Document.prototype.getNodesByType = function ( type, sort ) {
  *
  * @param {Array} data Snippet of linear model data to insert
  * @param {number} offset Offset in the linear model where the caller wants to insert data
- * @return {Object}
- * @return {Array} return.data Possibly modified copy of `data`
- * @return {number} return.offset Possibly modified offset
- * @return {number} return.remove Number of elements to remove after the modified `offset`
- * @return {number} [return.insertedDataOffset] Offset of intended insertion within fixed up data
- * @return {number} [return.insertedDataLength] Length of intended insertion within fixed up data
+ * @return {ve.dm.Document.FixedInsertion}
  */
 ve.dm.Document.prototype.fixupInsertion = function ( data, offset ) {
 	var

src/dm/ve.dm.Surface.js

@@ -272,10 +272,19 @@ ve.dm.Surface.prototype.resetHistoryTrackingInterval = function () {
 	this.startHistoryTracking();
 };
 
+/**
+ * @typedef {Object} UndoStackItem
+ * @memberof ve.dm.Surface
+ * @property {number} start
+ * @property {ve.dm.Transaction[]} transactions
+ * @property {ve.dm.Selection} selection
+ * @property {ve.dm.Selection} selectionBefore
+ */
+
 /**
  * Get a list of all applied history states.
  *
- * @return {Object[]} List of applied transaction stacks
+ * @return {ve.dm.Surface.UndoStackItem[]} List of applied transaction stacks
  */
 ve.dm.Surface.prototype.getHistory = function () {
 	var appliedUndoStack = this.undoStack.slice( 0, this.undoStack.length - this.undoIndex );
@@ -294,13 +303,18 @@ ve.dm.Surface.prototype.isStaging = function () {
 	return this.stagingStack.length > 0;
 };
 
+/**
+ * @typedef {Object} StagingState
+ * @memberof ve.dm.Surface
+ * @property {ve.dm.Transaction[]} transactions Staging transactions
+ * @property {ve.dm.Selection} selectionBefore Selection before transactions were applied
+ * @property {boolean} allowUndo Allow undo while staging
+ */
+
 /**
  * Get the staging state at the current staging stack depth
  *
- * @return {Object|undefined} staging Staging state object, or undefined if not staging
- * @return {ve.dm.Transaction[]} staging.transactions Staging transactions
- * @return {ve.dm.Selection} staging.selectionBefore Selection before transactions were applied
- * @return {boolean} staging.allowUndo Allow undo while staging
+ * @return {ve.dm.Surface.StagingState|undefined} staging Staging state object, or undefined if not staging
  */
 ve.dm.Surface.prototype.getStaging = function () {
 	return this.stagingStack[ this.stagingStack.length - 1 ];

src/dm/ve.dm.Transaction.js

@@ -587,15 +587,20 @@ ve.dm.Transaction.prototype.getModifiedRange = function ( doc, options ) {
 	return new ve.Range( start, end );
 };
 
+/**
+ * @typedef {Object} RangeAndLengthDiff
+ * @memberof ve.dm.Transaction
+ * @property {number} [start] Start offset of the active range
+ * @property {number} [end] End offset of the active range
+ * @property {number} [startOpIndex] Start operation index of the active range
+ * @property {number} [endOpIndex] End operation index of the active range
+ * @property {number} diff Length change the transaction causes
+ */
+
 /**
  * Calculate active range and length change
  *
- * @return {Object} Active range and length change
- * @return {number|undefined} return.start Start offset of the active range
- * @return {number|undefined} return.end End offset of the active range
- * @return {number|undefined} return.startOpIndex Start operation index of the active range
- * @return {number|undefined} return.endOpIndex End operation index of the active range
- * @return {number} return.diff Length change the transaction causes
+ * @return {ve.dm.Transaction.RangeAndLengthDiff} Active range and length change
  */
 ve.dm.Transaction.prototype.getActiveRangeAndLengthDiff = function () {
 	var offset = 0,

src/dm/ve.dm.TreeCursor.js

@@ -129,6 +129,18 @@ ve.dm.TreeCursor.prototype.checkLinearOffset = function () {
 	}
 };
 
+/**
+ * @typedef {Object} Step
+ * @memberof ve.dm.TreeCursor
+ * @property {string} type open|close|cross|crosstext
+ * @property {number} length Linear length of the step (integer >= 1)
+ * @property {number[]} path Offset path from the root to the node containing the stepped item
+ * @property {ve.dm.Node|null} node The node containing the stepped item
+ * @property {number} offset The offset of the stepped item within its parent
+ * @property {number} [offsetLength] Number of characters 'crosstext' passed
+ * @property {ve.dm.Node} [item] The node stepped into/out of/across (absent for 'crosstext')
+ */
+
 /**
  * Take a single step in the walk, consuming no more than a given linear model length
  *
@@ -138,14 +150,7 @@ ve.dm.TreeCursor.prototype.checkLinearOffset = function () {
  * See https://phabricator.wikimedia.org/T162762 for the algorithm
  *
  * @param {number} maxLength Maximum linear model length to step over (integer >= 1)
- * @return {Object|null} The type of step taken, or null if there are no more steps
- * @return {string} return.type open|close|cross|crosstext
- * @return {number} return.length Linear length of the step (integer >= 1)
- * @return {number[]} return.path Offset path from the root to the node containing the stepped item
- * @return {ve.dm.Node|null} return.node The node containing the stepped item
- * @return {number} return.offset The offset of the stepped item within its parent
- * @return {number} [return.offsetLength] Number of characters 'crosstext' passed
- * @return {ve.dm.Node} [return.item] The node stepped into/out of/across (absent for 'crosstext')
+ * @return {ve.dm.TreeCursor.Step|null} The type of step taken, or null if there are no more steps
  */
 ve.dm.TreeCursor.prototype.stepAtMost = function ( maxLength ) {
 	if ( !this.node ) {

src/dm/ve.dm.TreeModifier.js

@@ -794,7 +794,7 @@ ve.dm.TreeModifier.prototype.pushInsertTextOp = function ( data ) {
 /**
  * Push into treeOps a move of a node to the current inserter position
  *
- * @param {Object} removerStep The remover step over the node; see ve.dm.TreeCursor#stepAtMost
+ * @param {ve.dm.TreeCursor.Step} removerStep The remover step over the node
  */
 ve.dm.TreeModifier.prototype.pushMoveNodeOp = function ( removerStep ) {
 	var rawRemoverPosition = this.getRawRemoverPosition( removerStep ),
@@ -818,7 +818,7 @@ ve.dm.TreeModifier.prototype.pushMoveNodeOp = function ( removerStep ) {
 /**
  * Push into treeOps a move of some text to the current inserter position
  *
- * @param {Object} removerStep The remover step over the text; see ve.dm.TreeCursor#stepAtMost
+ * @param {ve.dm.TreeCursor.Step} removerStep The remover step over the text
  */
 ve.dm.TreeModifier.prototype.pushMoveTextOp = function ( removerStep ) {
 	var length = removerStep.type === 'crosstext' ?
@@ -845,7 +845,7 @@ ve.dm.TreeModifier.prototype.pushMoveTextOp = function ( removerStep ) {
 /**
  * Push into treeOps a removal of a node
  *
- * @param {Object} removerStep The remover step over the node; see ve.dm.TreeCursor#stepAtMost
+ * @param {ve.dm.TreeCursor.Step} removerStep The remover step over the node
  */
 ve.dm.TreeModifier.prototype.pushRemoveNodeOp = function ( removerStep ) {
 	var rawRemoverPosition = this.getRawRemoverPosition( removerStep ),
@@ -862,7 +862,7 @@ ve.dm.TreeModifier.prototype.pushRemoveNodeOp = function ( removerStep ) {
 /**
  * Push into treeOps a removal of some text
  *
- * @param {Object} removerStep The remover step over the text; see ve.dm.TreeCursor#stepAtMost
+ * @param {ve.dm.TreeCursor.Step} removerStep The remover step over the text
  */
 ve.dm.TreeModifier.prototype.pushRemoveTextOp = function ( removerStep ) {
 	var rawRemoverPosition = this.getRawRemoverPosition( removerStep );
@@ -927,7 +927,7 @@ ve.dm.TreeModifier.prototype.modifyAdjustmentTree = function ( rawPosition, diff
 /**
  * Get the raw position of a node stepped over by the remover
  *
- * @param {Object} step Remover step; see ve.dm.TreeCursor#stepAtMost
+ * @param {ve.dm.TreeCursor.Step} step Remover step
  * @return {number[]} The pathAndOffset, with offsets inside a ContentBranchNode linearized
  */
 ve.dm.TreeModifier.prototype.getRawRemoverPosition = function ( step ) {

src/dm/ve.dm.VisualDiff.js

@@ -152,13 +152,21 @@ ve.dm.VisualDiff.prototype.freezeInternalListIndices = function ( doc ) {
 	}
 };
 
+/**
+ * @typedef {ve.dm.VisualDiff.ListDiff} DocDiff
+ * @memberof ve.dm.VisualDiff
+ * @property {ve.dm.Node} oldRoot
+ * @property {ve.dm.Node} newRoot
+ * @property {ve.dm.VisualDiff.AttributeDiff} attributeChange
+ */
+
 /**
  * Diff two nodes as documents, comaparing their children as lists.
  *
  * @param {ve.dm.Node} oldRoot Old root
  * @param {ve.dm.Node} newRoot New root
  * @param {boolean} skipInternalLists Skip internal list nodes
- * @return {Object} Object containing diff information
+ * @return {ve.dm.VisualDiff.DocDiff} Object containing diff information
  */
 ve.dm.VisualDiff.prototype.diffDocs = function ( oldRoot, newRoot, skipInternalLists ) {
 	var oldChildren = oldRoot.children;
@@ -190,12 +198,23 @@ ve.dm.VisualDiff.prototype.diffDocs = function ( oldRoot, newRoot, skipInternalL
 	return diff;
 };
 
+/**
+ * @typedef {Object} ListDiff
+ * @memberof ve.dm.VisualDiff
+ * @property {ve.dm.Node[]} oldNodes
+ * @property {ve.dm.Node[]} newNodes
+ * @property {Object} oldToNew
+ * @property {Object} newToOld
+ * @property {number[]} remove
+ * @property {number[]} insert
+ */
+
 /**
  * Get the diff between two lists of nodes.
  *
  * @param {ve.dm.Node[]} oldNodes Nodes from the old document
  * @param {ve.dm.Node[]} newNodes Nodes from the new document
- * @return {Object} Object containing diff information
+ * @return {ve.dm.VisualDiff.ListDiff} Object containing diff information
  */
 ve.dm.VisualDiff.prototype.diffList = function ( oldNodes, newNodes ) {
 	var oldNodesToDiff = [],
@@ -435,7 +454,6 @@ ve.dm.VisualDiff.prototype.findModifiedNodes = function ( oldIndices, newIndices
 			diff.insert.push( newIndices[ j ] );
 		}
 	}
-
 };
 
 /**
@@ -445,7 +463,7 @@ ve.dm.VisualDiff.prototype.findModifiedNodes = function ( oldIndices, newIndices
  * @param {ve.dm.Node} oldNode Node from the old document
  * @param {ve.dm.Node} newNode Node from the new document
  * @param {boolean} [noTreeDiff] Don't perform a tree diff of the nodes (used internally to avoid recursion)
- * @return {Array|boolean} The diff, or false if the nodes are too different
+ * @return {ve.dm.VisualDiff.LeafDiff|ve.dm.VisualDiff.ListDiff|ve.dm.VisualDiff.DocDiff|ve.dm.VisualDiff.TreeDiff|boolean} The diff, or false if the nodes are too different
  */
 ve.dm.VisualDiff.prototype.diffNodes = function ( oldNode, newNode, noTreeDiff ) {
 	// If not diff comparable, return no diff
@@ -468,12 +486,19 @@ ve.dm.VisualDiff.prototype.diffNodes = function ( oldNode, newNode, noTreeDiff )
 	return diff;
 };
 
+/**
+ * @typedef {Object} LeafDiff
+ * @memberof ve.dm.VisualDiff
+ * @property {ve.dm.VisualDiff.AttributeDiff|boolean} attributeChange
+ * @property {Array|boolean} linearDiff
+ */
+
 /**
  * Diff two leaf nodes
  *
  * @param {ve.dm.Node} oldNode Node from the old document
  * @param {ve.dm.Node} newNode Node from the new document
- * @return {Object|boolean} Leaf diff, or false if the nodes are too different
+ * @return {ve.dm.VisualDiff.LeafDiff|boolean} Leaf diff, or false if the nodes are too different
  * or if the diff timed out
  */
 ve.dm.VisualDiff.prototype.diffLeafNodes = function ( oldNode, newNode ) {
@@ -507,7 +532,7 @@ ve.dm.VisualDiff.prototype.diffLeafNodes = function ( oldNode, newNode ) {
  *
  * @param {ve.dm.Node} oldNode Node from the old document
  * @param {ve.dm.Node} newNode Node from the new document
- * @return {Object|boolean} Leaf diff, or false if the nodes are too different
+ * @return {ve.dm.VisualDiff.ListDiff|boolean} Leaf diff, or false if the nodes are too different
  * or if the diff timed out
  */
 ve.dm.VisualDiff.prototype.diffListNodes = function ( oldNode, newNode ) {
@@ -674,6 +699,19 @@ ve.dm.VisualDiff.prototype.alignTrees = function ( oldTree, newTree ) {
 	return transactions[ oldTree.orderedNodes.length - 1 ][ newTree.orderedNodes.length - 1 ];
 };
 
+/**
+ * @typedef {Object} TreeDiff
+ * @memberof ve.dm.VisualDiff
+ * @property {ve.DiffTreeNode[]} oldTreeOrderedNodes - Nodes of the old tree, deepest first then in document order
+ * @property {ve.DiffTreeNode[]} newTreeOrderedNodes - Nodes of the new tree, deepest first then in document order
+ * @property {Array[]} treeDiff - Node correspondences as indexes in *TreeOrderedNodes
+ * @property {number[]} treeDiff.i - The i'th correspondence [ oldTreeOrderedNodes index, newTreeOrderedNodes index ]
+ * @property {Object|null} diffInfo - Linear diffs applying to each corresponding node pair
+ * @property {Object} diffInfo.i - Linear diff applying to i'th node in newTreeOrderedNodes
+ * @property {Array|boolean} diffInfo.i.linearDiff - Output of #diffContent
+ * @property {ve.dm.VisualDiff.AttributeDiff|boolean} diffInfo.i.attributeChange Attribute diff
+ */
+
 /**
  * Do a tree diff. There are three steps: (1) Do a tree diff to find the minimal
  * transactions between the old tree and the new tree. Allowed transactions
@@ -693,15 +731,7 @@ ve.dm.VisualDiff.prototype.alignTrees = function ( oldTree, newTree ) {
  *
  * @param {ve.dm.Node} oldTreeNode Node from the old document
  * @param {ve.dm.Node} newTreeNode Node from the new document
- * @return {Object|boolean} Diff object, or false or false if the nodes are too different or if the diff timed out
- * @return {ve.DiffTreeNode[]} return.oldTreeOrderedNodes nodes of the old tree, deepest first then in document order
- * @return {ve.DiffTreeNode[]} return.newTreeOrderedNodes nodes of the new tree, deepest first then in document order
- * @return {Array[]} return.treeDiff Node correspondences as indexes in *TreeOrderedNodes
- * @return {number[]} return.treeDiff.i The i'th correspondence [ oldTreeOrderedNodes index, newTreeOrderedNodes index ]
- * @return {Object|null} return.diffInfo Linear diffs applying to each corresponding node pair
- * @return {Object} return.diffInfo.i Linear diff applying to i'th node in newTreeOrderedNodes
- * @return {Array|boolean} return.diffInfo.i.linearDiff Output of #diffContent
- * @return {Array|boolean} return.diffInfo.i.attributeChange Output of #diffAttributes
+ * @return {ve.dm.VisualDiff.TreeDiff|boolean} Diff object, or false if the nodes are too different or if the diff timed out.
  */
 ve.dm.VisualDiff.prototype.diffTreeNodes = function ( oldTreeNode, newTreeNode ) {
 	var changeRecord = {
@@ -779,13 +809,20 @@ ve.dm.VisualDiff.prototype.diffTreeNodes = function ( oldTreeNode, newTreeNode )
 	};
 };
 
+/**
+ * @typedef {Object} AttributeDiff
+ * @memberof ve.dm.VisualDiff
+ * @property {Object} oldAttributes
+ * @property {Object} newAttributes
+ */
+
 /**
  * Find the difference between attributes of two nodes
  *
  * @param {ve.dm.Node} oldNode Node from the old document
  * @param {ve.dm.Node} newNode Node from the new document
  * @param {string} [diffTypeAsAttribute] Diff the type of the node as an attribute with this name
- * @return {Object|boolean} The attributes diff, or false if unchanged
+ * @return {ve.dm.VisualDiff.AttributeDiff|boolean} The attributes diff, or false if unchanged
  */
 ve.dm.VisualDiff.prototype.diffAttributes = function ( oldNode, newNode, diffTypeAsAttribute ) {
 	var oldAttributes = oldNode.getAttributes();
@@ -879,6 +916,19 @@ ve.dm.VisualDiff.prototype.underDiffThreshold = function ( changeRecord ) {
 	return changeRecord.keepLength < this.diffThreshold * changeRecord.diffLength;
 };
 
+/**
+ * @typedef {Object} MetaListDiff
+ * @memberof ve.dm.VisualDiff
+ * @property {Object.<string,ve.dm.VisualDiff.ListDiff>} groups List diffs, indexed by group
+ */
+
+/**
+ * Calculate a meta list diff
+ *
+ * @param {ve.dm.MetaList} oldMetaList
+ * @param {ve.dm.MetaList} newMetaList
+ * @return {ve.dm.VisualDiff.MetaListDiff}
+ */
 ve.dm.VisualDiff.prototype.getMetaListDiff = function ( oldMetaList, newMetaList ) {
 	var visualDiff = this;
 	var oldItemsByGroup = {};
@@ -907,13 +957,23 @@ ve.dm.VisualDiff.prototype.getMetaListDiff = function ( oldMetaList, newMetaList
 	return groupDiffs;
 };
 
+/**
+ * @typedef {Object} InternalListDiff
+ * @memberof ve.dm.VisualDiff
+ * @property {Object.<string,ve.dm.VisualDiff.ListDiff>} groups List diffs, indexed by group
+ * @property {ve.dm.InternalListNode} oldDocInternalListNode
+ * @property {ve.dm.InternalListNode} newDocInternalListNode
+ */
+
 /*
  * Get the diff between the old document's internal list and the new document's
  * internal list. The diff is grouped by list group, and each node in each list
  * group is marked as removed, inserted, the same, or changed (in which case the
  * linear diff is given).
  *
- * @return {Object} Internal list diff object
+ * @param {ve.dm.InternalList} oldInternalList
+ * @param {ve.dm.InternalList} newInternalList
+ * @return {ve.dm.VisualDiff.InternalListDiff} Internal list diff object
  */
 ve.dm.VisualDiff.prototype.getInternalListDiff = function ( oldInternalList, newInternalList ) {
 	var oldDocNodeGroups = oldInternalList.getNodeGroups(),

src/ui/ve.ui.SequenceRegistry.js

@@ -40,7 +40,8 @@ ve.ui.SequenceRegistry.prototype.register = function ( sequence ) {
 /**
  * Matching sequence and corresponding range
  *
- * @type {Object} Match
+ * @typedef {Object} Match
+ * @memberof ve.ui.SequenceRegistry
  * @property {ve.ui.Sequence} sequence
  * @property {ve.Range} range
  */
@@ -52,7 +53,7 @@ ve.ui.SequenceRegistry.prototype.register = function ( sequence ) {
  * @param {number} offset
  * @param {boolean} [isPaste] Whether this in the context of a paste
  * @param {boolean} [isDelete] Whether this is after content being deleted
- * @return {Match[]} Array of matching sequences, and the corresponding range of the match for each.
+ * @return {ve.ui.SequenceRegistry.Match[]} Array of matching sequences, and the corresponding range of the match for each.
  */
 ve.ui.SequenceRegistry.prototype.findMatching = function ( data, offset, isPaste, isDelete ) {
 	// To avoid blowup when matching RegExp sequences, we're going to grab

src/ui/widgets/ve.ui.DimensionsWidget.js

@@ -198,12 +198,17 @@ ve.ui.DimensionsWidget.prototype.setDimensions = function ( dimensions ) {
 	return this;
 };
 
+/**
+ * @typedef {Object} Dimensions
+ * @memberof ve.ui.DimensionsWidget
+ * @property {number} width The value of the width input
+ * @property {number} height The value of the height input
+ */
+
 /**
  * Return the current dimension values in the widget
  *
- * @return {Object} dimensions The width and height values of the inputs
- * @return {number} dimensions.width The value of the width input
- * @return {number} dimensions.height The value of the height input
+ * @return {ve.ui.DimensionsWidget.Dimensions} dimensions The width and height values of the inputs
  */
 ve.ui.DimensionsWidget.prototype.getDimensions = function () {
 	return {

src/ve.utils.js

@@ -1082,6 +1082,14 @@ ve.compareDocumentOrder = function ( node1, offset1, node2, offset2 ) {
 	);
 };
 
+/**
+ * @typedef {Object} DomPosition
+ * @memberof ve
+ * @property {Node|null} node The node, or null if we stepped past the root node
+ * @property {number|null} offset The offset, or null if we stepped past the root node
+ * @property {ve.PositionStep[]} steps Steps taken
+ */
+
 /**
  * Get the closest matching DOM position in document order (forward or reverse)
  *
@@ -1110,10 +1118,7 @@ ve.compareDocumentOrder = function ( node1, offset1, node2, offset2 ) {
  * @param {Object} options
  * @param {Function|string} [options.noDescend] Selector or function: nodes to skip over
  * @param {Function} [options.stop] Boolean-valued ve.PositionStep test function
- * @return {Object} The adjacent DOM position encountered
- * @return {Node|null} return.node The node, or null if we stepped past the root node
- * @return {number|null} return.offset The offset, or null if we stepped past the root node
- * @return {Object[]} return.steps Steps taken {node: x, type: leave|cross|enter|internal, offset: n}
+ * @return {ve.DomPosition} The adjacent DOM position encountered
  * @see ve#isHardCursorStep
  */
 ve.adjacentDomPosition = function ( position, direction, options ) {
@@ -1251,15 +1256,20 @@ ve.rejectsCursor = function ( node ) {
 	return node.contentEditable === 'false';
 };
 
+/**
+ * @typedef {Object} ChangeOffsets
+ * @memberof ve
+ * @return {number} start Offset from start of first changed element
+ * @return {number} end Offset from end of last changed element (nonoverlapping with start)
+ */
+
 /**
  * Count the common elements at the start and end of two sequences
  *
  * @param {Array|string} before The original sequence
  * @param {Array|string} after The modified sequence
  * @param {Function} [equals] Two-argument comparison returning boolean (defaults to ===)
- * @return {Object|null} Change offsets (valid in both sequences), or null if unchanged
- * @return {number} return.start Offset from start of first changed element
- * @return {number} return.end Offset from end of last changed element (nonoverlapping with start)
+ * @return {ve.ChangeOffsets|null} Change offsets (valid in both sequences), or null if unchanged
  */
 ve.countEdgeMatches = function ( before, after, equals ) {
 	if ( !equals ) {