From 07ac1d03e3284e74e9608c21a10bb1e0a81710aa Mon Sep 17 00:00:00 2001 From: Kevin Jahns Date: Thu, 11 Apr 2019 23:34:56 +0200 Subject: [PATCH] fix jsdoc --- src/structs/AbstractItem.js | 22 ++++++++-- src/types/AbstractType.js | 4 +- src/types/YText.js | 82 ++++++++++++++++++++++++++++--------- src/utils/EventHandler.js | 7 ++-- src/utils/Transaction.js | 2 +- 5 files changed, 87 insertions(+), 30 deletions(-) diff --git a/src/structs/AbstractItem.js b/src/structs/AbstractItem.js index 31bd3767..d37e35b3 100644 --- a/src/structs/AbstractItem.js +++ b/src/structs/AbstractItem.js @@ -33,6 +33,7 @@ import * as binary from 'lib0/binary.js' * @param {AbstractItem} leftItem * @param {number} diff * @return {AbstractItem} + * * @function * @private */ @@ -567,6 +568,21 @@ export const changeItemRefOffset = (item, offset) => { item.left = createID(item.id.client, item.id.clock - 1) } +export class ItemParams { + /** + * @param {AbstractItem?} left + * @param {AbstractItem?} right + * @param {AbstractType?} parent + * @param {string|null} parentSub + */ + constructor (left, right, parent, parentSub) { + this.left = left + this.right = right + this.parent = parent + this.parentSub = parentSub + } +} + /** * Outsourcing some of the logic of computing the item params from a received struct. * If parent === null, it is expected to gc the read struct. Otherwise apply it. @@ -578,7 +594,7 @@ export const changeItemRefOffset = (item, offset) => { * @param {ID|null} parentid * @param {string|null} parentSub * @param {string|null} parentYKey - * @return {{left:AbstractItem?,right:AbstractItem?,parent:AbstractType?,parentSub:string?}} + * @return {ItemParams} * * @private * @function @@ -611,7 +627,5 @@ export const computeItemParams = (transaction, store, leftid, rightid, parentid, } else { throw error.unexpectedCase() } - return { - left, right, parent, parentSub - } + return new ItemParams(left, right, parent, parentSub) } diff --git a/src/types/AbstractType.js b/src/types/AbstractType.js index 42f4736b..617304b4 100644 --- a/src/types/AbstractType.js +++ b/src/types/AbstractType.js @@ -30,7 +30,7 @@ import * as encoding from 'lib0/encoding.js' // eslint-disable-line * @param {EventType} event */ export const callTypeObservers = (type, transaction, event) => { - callEventHandlerListeners(type._eH, [event, transaction]) + callEventHandlerListeners(type._eH, event, transaction) const changedParentTypes = transaction.changedParentTypes while (true) { // @ts-ignore @@ -572,7 +572,7 @@ export const typeMapGetSnapshot = (parent, key, snapshot) => { /** * @param {Map} map - * @return {Iterator<[string,AbstractItem]>} + * @return {IterableIterator>} * * @private * @function diff --git a/src/types/YText.js b/src/types/YText.js index 1906daf5..f79b65da 100644 --- a/src/types/YText.js +++ b/src/types/YText.js @@ -22,6 +22,41 @@ import { import * as decoding from 'lib0/decoding.js' // eslint-disable-line import * as encoding from 'lib0/encoding.js' +export class ItemListPosition { + /** + * @param {AbstractItem|null} left + * @param {AbstractItem|null} right + */ + constructor (left, right) { + this.left = left + this.right = right + } +} + +export class ItemTextListPosition extends ItemListPosition { + /** + * @param {AbstractItem|null} left + * @param {AbstractItem|null} right + * @param {Map} currentAttributes + */ + constructor (left, right, currentAttributes) { + super(left, right) + this.currentAttributes = currentAttributes + } +} + +export class ItemInsertionResult extends ItemListPosition { + /** + * @param {AbstractItem|null} left + * @param {AbstractItem|null} right + * @param {Map} negatedAttributes + */ + constructor (left, right, negatedAttributes) { + super(left, right) + this.negatedAttributes = negatedAttributes + } +} + /** * @param {Transaction} transaction * @param {StructStore} store @@ -29,7 +64,7 @@ import * as encoding from 'lib0/encoding.js' * @param {AbstractItem|null} left * @param {AbstractItem|null} right * @param {number} count - * @return {{left:AbstractItem|null,right:AbstractItem|null,currentAttributes:Map}} + * @return {ItemTextListPosition} * * @private * @function @@ -57,7 +92,7 @@ const findNextPosition = (transaction, store, currentAttributes, left, right, co left = right right = right.right } - return { left, right, currentAttributes } + return new ItemTextListPosition(left, right, currentAttributes) } /** @@ -65,7 +100,7 @@ const findNextPosition = (transaction, store, currentAttributes, left, right, co * @param {StructStore} store * @param {AbstractType} parent * @param {number} index - * @return {{left:AbstractItem|null,right:AbstractItem|null,currentAttributes:Map}} + * @return {ItemTextListPosition} * * @private * @function @@ -85,7 +120,7 @@ const findPosition = (transaction, store, parent, index) => { * @param {AbstractItem|null} left * @param {AbstractItem|null} right * @param {Map} negatedAttributes - * @return {{left:AbstractItem|null,right:AbstractItem|null}} + * @return {ItemListPosition} * * @private * @function @@ -137,7 +172,7 @@ const updateCurrentAttributes = (currentAttributes, item) => { * @param {AbstractItem|null} right * @param {Map} currentAttributes * @param {Object} attributes - * @return {{left:AbstractItem|null,right:AbstractItem|null}} + * @return {ItemListPosition} * * @private * @function @@ -160,7 +195,7 @@ const minimizeAttributeChanges = (left, right, currentAttributes, attributes) => left = right right = right.right } - return { left, right } + return new ItemListPosition(left, right) } /** @@ -170,7 +205,7 @@ const minimizeAttributeChanges = (left, right, currentAttributes, attributes) => * @param {AbstractItem|null} right * @param {Map} currentAttributes * @param {Object} attributes - * @return {{left:AbstractItem|null,right:AbstractItem|null,negatedAttributes:Map}} + * @return {ItemInsertionResult} * * @private * @function @@ -188,7 +223,7 @@ const insertAttributes = (transaction, parent, left, right, currentAttributes, a left.integrate(transaction) } } - return { left, right, negatedAttributes } + return new ItemInsertionResult(left, right, negatedAttributes) } /** @@ -199,7 +234,7 @@ const insertAttributes = (transaction, parent, left, right, currentAttributes, a * @param {Map} currentAttributes * @param {string} text * @param {Object} attributes - * @return {{left:AbstractItem|null,right:AbstractItem|null}} + * @return {ItemListPosition} * * @private * @function @@ -232,7 +267,7 @@ const insertText = (transaction, parent, left, right, currentAttributes, text, a * @param {Map} currentAttributes * @param {number} length * @param {Object} attributes - * @return {{left:AbstractItem|null,right:AbstractItem|null}} + * @return {ItemListPosition} * * @private * @function @@ -282,17 +317,16 @@ const formatText = (transaction, parent, left, right, currentAttributes, length, /** * @param {Transaction} transaction - * @param {AbstractType} parent * @param {AbstractItem|null} left * @param {AbstractItem|null} right * @param {Map} currentAttributes * @param {number} length - * @return {{left:AbstractItem|null,right:AbstractItem|null}} + * @return {ItemListPosition} * * @private * @function */ -const deleteText = (transaction, parent, left, right, currentAttributes, length) => { +const deleteText = (transaction, left, right, currentAttributes, length) => { while (length > 0 && right !== null) { if (right.deleted === false) { switch (right.constructor) { @@ -343,6 +377,14 @@ const deleteText = (transaction, parent, left, right, currentAttributes, length) * @typedef {Object} TextAttributes */ +/** + * @typedef {Object} DeltaItem + * @property {number|undefined} DeltaItem.delete + * @property {number|undefined} DeltaItem.retain + * @property {string|undefined} DeltaItem.string + * @property {Object} DeltaItem.attributes + */ + /** * Event that describes the changes on a YText type. */ @@ -355,7 +397,7 @@ class YTextEvent extends YEvent { super(ytext, transaction) /** * @private - * @type {Array<{delete:number|undefined,retain:number|undefined,insert:string|undefined,attributes:Object}>|null} + * @type {Array|null} */ this._delta = null } @@ -363,7 +405,7 @@ class YTextEvent extends YEvent { * Compute the changes in the delta format. * A {@link https://quilljs.com/docs/delta/|Quill Delta}) that represents the changes on the document. * - * @type {Array<{delete:number|undefined,retain:number|undefined,insert:string|undefined,attributes:Object}>} + * @type {Array} * * @public */ @@ -373,7 +415,7 @@ class YTextEvent extends YEvent { // @ts-ignore transact(y, transaction => { /** - * @type {Array<{delete:number|undefined,retain:number|undefined,insert:string|undefined,attributes:Object}>} + * @type {Array} */ const delta = [] const currentAttributes = new Map() // saves all current attributes for insert @@ -680,9 +722,9 @@ export class YText extends AbstractType { if (this._y !== null) { transact(this._y, transaction => { /** - * @type {{left:AbstractItem|null,right:AbstractItem|null}} + * @type {ItemListPosition} */ - let pos = { left: null, right: this._start } + let pos = new ItemListPosition(null, this._start) const currentAttributes = new Map() for (let i = 0; i < delta.length; i++) { const op = delta[i] @@ -691,7 +733,7 @@ export class YText extends AbstractType { } else if (op.retain !== undefined) { pos = formatText(transaction, this, pos.left, pos.right, currentAttributes, op.retain, op.attributes || {}) } else if (op.delete !== undefined) { - pos = deleteText(transaction, this, pos.left, pos.right, currentAttributes, op.delete) + pos = deleteText(transaction, pos.left, pos.right, currentAttributes, op.delete) } } }) @@ -839,7 +881,7 @@ export class YText extends AbstractType { if (y !== null) { transact(y, transaction => { const { left, right, currentAttributes } = findPosition(transaction, y.store, this, index) - deleteText(transaction, this, left, right, currentAttributes, length) + deleteText(transaction, left, right, currentAttributes, length) }) } } diff --git a/src/utils/EventHandler.js b/src/utils/EventHandler.js index 427430e9..ea50b0f1 100644 --- a/src/utils/EventHandler.js +++ b/src/utils/EventHandler.js @@ -72,10 +72,11 @@ export const removeAllEventHandlerListeners = eventHandler => { * * @template ARG0,ARG1 * @param {EventHandler} eventHandler - * @param {[ARG0,ARG1]} args + * @param {ARG0} arg0 + * @param {ARG1} arg1 * * @private * @function */ -export const callEventHandlerListeners = (eventHandler, args) => - f.callAll(eventHandler.l, args) +export const callEventHandlerListeners = (eventHandler, arg0, arg1) => + f.callAll(eventHandler.l, [arg0, arg1]) diff --git a/src/utils/Transaction.js b/src/utils/Transaction.js index bdb66cf2..94793fca 100644 --- a/src/utils/Transaction.js +++ b/src/utils/Transaction.js @@ -157,7 +157,7 @@ export const transact = (y, f) => { }) // we don't need to check for events.length // because we know it has at least one element - callEventHandlerListeners(type._dEH, [events, transaction]) + callEventHandlerListeners(type._dEH, events, transaction) }) // only call afterTransaction listeners if anything changed transaction.afterState = getStates(transaction.y.store)