fix jsdoc

2019-04-11 23:34:56 +02:00
parent cbcf1facb8
commit 07ac1d03e3
5 changed files with 87 additions and 30 deletions
--- 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<YEvent>?} 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<YEvent>?,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)
 }
--- 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<string,AbstractItem>} map
- * @return {Iterator<[string,AbstractItem]>}
+ * @return {IterableIterator<Array<any>>}
 *
 * @private
 * @function
--- 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<string,any>} 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<string,any>} 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<string,any>}}
+ * @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<any>} parent
 * @param {number} index
- * @return {{left:AbstractItem|null,right:AbstractItem|null,currentAttributes:Map<string,any>}}
+ * @return {ItemTextListPosition}
 *
 * @private
 * @function
@@ -85,7 +120,7 @@ const findPosition = (transaction, store, parent, index) => {
 * @param {AbstractItem|null} left
 * @param {AbstractItem|null} right
 * @param {Map<string,any>} 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<string,any>} currentAttributes
 * @param {Object<string,any>} 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<string,any>} currentAttributes
 * @param {Object<string,any>} attributes
- * @return {{left:AbstractItem|null,right:AbstractItem|null,negatedAttributes:Map<string,any>}}
+ * @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<string,any>} currentAttributes
 * @param {string} text
 * @param {Object<string,any>} 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<string,any>} currentAttributes
 * @param {number} length
 * @param {Object<string,any>} 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<any>} parent
 * @param {AbstractItem|null} left
 * @param {AbstractItem|null} right
 * @param {Map<string,any>} 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<string,any>} 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<string,any>}>|null}
+     * @type {Array<DeltaItem>|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<string,any>}>}
+   * @type {Array<DeltaItem>}
   *
   * @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<string,any>}>}
+         * @type {Array<DeltaItem>}
         */
        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)
      })
    }
  }
--- a/src/utils/EventHandler.js
+++ b/src/utils/EventHandler.js
@@ -72,10 +72,11 @@ export const removeAllEventHandlerListeners = eventHandler => {
 *
 * @template ARG0,ARG1
 * @param {EventHandler<ARG0,ARG1>} 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])
--- 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)