From 31ff7ac78c59077dce165f96d038a24eda54bb17 Mon Sep 17 00:00:00 2001 From: Kevin Jahns Date: Thu, 11 Apr 2019 13:18:35 +0200 Subject: [PATCH] improve jsdoc comments --- README.v13.md | 6 +- src/internals.js | 2 +- src/structs/AbstractItem.js | 25 +++++++- src/structs/AbstractStruct.js | 7 ++- src/structs/GC.js | 10 +++- src/structs/ItemBinary.js | 12 +++- src/structs/ItemDeleted.js | 12 +++- src/structs/ItemEmbed.js | 12 +++- src/structs/ItemFormat.js | 12 +++- src/structs/ItemJSON.js | 12 +++- src/structs/ItemString.js | 10 +++- src/structs/ItemType.js | 13 ++++- src/types/AbstractType.js | 61 ++++++++++++++++++-- src/types/YArray.js | 15 ++++- src/types/YMap.js | 19 +++++- src/types/YText.js | 53 ++++++++++++----- src/types/YXmlElement.js | 12 +++- src/types/YXmlEvent.js | 11 +--- src/types/YXmlHook.js | 9 ++- src/types/YXmlText.js | 8 ++- src/utils/DeleteSet.js | 26 +++++++++ src/utils/EventHandler.js | 17 ++++++ src/utils/ID.js | 17 +++++- src/utils/Snapshot.js | 19 +++++- src/utils/StructStore.js | 41 +++++++++++++ src/utils/Transaction.js | 13 ++++- src/utils/UndoManager.js | 19 ++++++ src/utils/Y.js | 35 ++++++----- src/utils/YEvent.js | 9 ++- src/utils/{structEncoding.js => encoding.js} | 47 ++++++++++----- src/utils/isParentOf.js | 6 +- src/utils/relativePosition.js | 21 +++++++ 32 files changed, 477 insertions(+), 114 deletions(-) rename src/utils/{structEncoding.js => encoding.js} (95%) diff --git a/README.v13.md b/README.v13.md index 8db4425e..16415017 100644 --- a/README.v13.md +++ b/README.v13.md @@ -74,9 +74,7 @@ Yjs does not hava any dependencies. Install this package with your favorite pack npm i yjs ``` -##### Tutorial - -In this *short* tutorial I will give an overview of the basic concepts in Yjs. +##### Quickstart Yjs itself only knows how to do conflict resolution. You need to choose a provider, that handles how document updates are distributed over the network. @@ -140,6 +138,8 @@ food.toJSON() // => { pancake: 10 } Now you understand how types are defined on a shared document. Next you can jump to one of the [tutorials on our website](https://yjs.website/tutorial-prosemirror.html) or continue reading about [Providers](#Providers), [Shared Types](#Shared-Types), and [Bindings](#Bindings). +## API + ## Providers In Yjs, a provider handles the communication channel to *authenticate*, *authorize*, and *exchange document updates*. Yjs ships with some existing providers. diff --git a/src/internals.js b/src/internals.js index dea4946c..6dd6b771 100644 --- a/src/internals.js +++ b/src/internals.js @@ -30,4 +30,4 @@ export * from './structs/ItemJSON.js' export * from './structs/ItemString.js' export * from './structs/ItemType.js' -export * from './utils/structEncoding.js' +export * from './utils/encoding.js' diff --git a/src/structs/AbstractItem.js b/src/structs/AbstractItem.js index 2f619c95..31bd3767 100644 --- a/src/structs/AbstractItem.js +++ b/src/structs/AbstractItem.js @@ -33,6 +33,8 @@ import * as binary from 'lib0/binary.js' * @param {AbstractItem} leftItem * @param {number} diff * @return {AbstractItem} + * @function + * @private */ export const splitItem = (transaction, leftItem, diff) => { const id = leftItem.id @@ -127,6 +129,7 @@ export class AbstractItem extends AbstractStruct { /** * @param {Transaction} transaction + * @private */ integrate (transaction) { const store = transaction.y.store @@ -257,6 +260,8 @@ export class AbstractItem extends AbstractStruct { * @param {AbstractType} parent * @param {string | null} parentSub * @return {AbstractItem} + * + * @private */ copy (id, left, origin, right, rightOrigin, parent, parentSub) { throw new Error('unimplemented') @@ -363,6 +368,8 @@ export class AbstractItem extends AbstractStruct { * @param {Transaction} transaction * @param {number} diff * @return {AbstractItem} + * + * @private */ splitAt (transaction, diff) { throw new Error('unimplemented') @@ -371,6 +378,8 @@ export class AbstractItem extends AbstractStruct { /** * @param {AbstractItem} right * @return {boolean} + * + * @private */ mergeWith (right) { if (compareIDs(right.origin, this.lastId) && this.right === right && compareIDs(this.rightOrigin, right.rightOrigin)) { @@ -386,8 +395,6 @@ export class AbstractItem extends AbstractStruct { * Mark this Item as deleted. * * @param {Transaction} transaction - * - * @private */ delete (transaction) { if (!this.deleted) { @@ -405,12 +412,16 @@ export class AbstractItem extends AbstractStruct { /** * @param {Transaction} transaction * @param {StructStore} store + * + * @private */ gcChildren (transaction, store) { } /** * @param {Transaction} transaction * @param {StructStore} store + * + * @private */ gc (transaction, store) { let r @@ -449,6 +460,7 @@ export class AbstractItem extends AbstractStruct { * @param {encoding.Encoder} encoder The encoder to write data to. * @param {number} offset * @param {number} encodingRef + * * @private */ write (encoder, offset, encodingRef) { @@ -487,6 +499,9 @@ export class AbstractItem extends AbstractStruct { } } +/** + * @private + */ export class AbstractItemRef extends AbstractStructRef { /** * @param {decoding.Decoder} decoder @@ -543,6 +558,9 @@ export class AbstractItemRef extends AbstractStructRef { /** * @param {AbstractItemRef} item * @param {number} offset + * + * @function + * @private */ export const changeItemRefOffset = (item, offset) => { item.id = createID(item.id.client, item.id.clock + offset) @@ -561,6 +579,9 @@ export const changeItemRefOffset = (item, offset) => { * @param {string|null} parentSub * @param {string|null} parentYKey * @return {{left:AbstractItem?,right:AbstractItem?,parent:AbstractType?,parentSub:string?}} + * + * @private + * @function */ export const computeItemParams = (transaction, store, leftid, rightid, parentid, parentSub, parentYKey) => { const left = leftid === null ? null : getItemCleanEnd(transaction, store, leftid) diff --git a/src/structs/AbstractStruct.js b/src/structs/AbstractStruct.js index 6e985464..2b576d85 100644 --- a/src/structs/AbstractStruct.js +++ b/src/structs/AbstractStruct.js @@ -6,7 +6,9 @@ import { import * as encoding from 'lib0/encoding.js' // eslint-disable-line import * as error from 'lib0/error.js' -// eslint-disable-next-line +/** + * @private + */ export class AbstractStruct { /** * @param {ID} id @@ -53,6 +55,9 @@ export class AbstractStruct { } } +/** + * @private + */ export class AbstractStructRef { /** * @param {ID} id diff --git a/src/structs/GC.js b/src/structs/GC.js index 715f01ce..4431dc53 100644 --- a/src/structs/GC.js +++ b/src/structs/GC.js @@ -1,6 +1,4 @@ -/** - * @module structs - */ + import { AbstractStructRef, AbstractStruct, @@ -14,6 +12,9 @@ import * as encoding from 'lib0/encoding.js' export const structGCRefNumber = 0 +/** + * @private + */ export class GC extends AbstractStruct { /** * @param {ID} id @@ -60,6 +61,9 @@ export class GC extends AbstractStruct { } } +/** + * @private + */ export class GCRef extends AbstractStructRef { /** * @param {decoding.Decoder} decoder diff --git a/src/structs/ItemBinary.js b/src/structs/ItemBinary.js index e4c19abd..917db5c4 100644 --- a/src/structs/ItemBinary.js +++ b/src/structs/ItemBinary.js @@ -1,6 +1,3 @@ -/** - * @module structs - */ import { AbstractItem, @@ -13,8 +10,14 @@ import { import * as encoding from 'lib0/encoding.js' import * as decoding from 'lib0/decoding.js' +/** + * @private + */ export const structBinaryRefNumber = 1 +/** + * @private + */ export class ItemBinary extends AbstractItem { /** * @param {ID} id @@ -55,6 +58,9 @@ export class ItemBinary extends AbstractItem { } } +/** + * @private + */ export class ItemBinaryRef extends AbstractItemRef { /** * @param {decoding.Decoder} decoder diff --git a/src/structs/ItemDeleted.js b/src/structs/ItemDeleted.js index d444145e..3b4f753f 100644 --- a/src/structs/ItemDeleted.js +++ b/src/structs/ItemDeleted.js @@ -1,6 +1,3 @@ -/** - * @module structs - */ import { AbstractItem, @@ -16,8 +13,14 @@ import { import * as encoding from 'lib0/encoding.js' import * as decoding from 'lib0/decoding.js' +/** + * @private + */ export const structDeletedRefNumber = 2 +/** + * @private + */ export class ItemDeleted extends AbstractItem { /** * @param {ID} id @@ -91,6 +94,9 @@ export class ItemDeleted extends AbstractItem { } } +/** + * @private + */ export class ItemDeletedRef extends AbstractItemRef { /** * @param {decoding.Decoder} decoder diff --git a/src/structs/ItemEmbed.js b/src/structs/ItemEmbed.js index 24f7a81b..a317dc4f 100644 --- a/src/structs/ItemEmbed.js +++ b/src/structs/ItemEmbed.js @@ -1,6 +1,3 @@ -/** - * @module structs - */ import { AbstractItem, @@ -13,8 +10,14 @@ import { import * as encoding from 'lib0/encoding.js' import * as decoding from 'lib0/decoding.js' +/** + * @private + */ export const structEmbedRefNumber = 3 +/** + * @private + */ export class ItemEmbed extends AbstractItem { /** * @param {ID} id @@ -52,6 +55,9 @@ export class ItemEmbed extends AbstractItem { } } +/** + * @private + */ export class ItemEmbedRef extends AbstractItemRef { /** * @param {decoding.Decoder} decoder diff --git a/src/structs/ItemFormat.js b/src/structs/ItemFormat.js index 92da6570..2a523a5e 100644 --- a/src/structs/ItemFormat.js +++ b/src/structs/ItemFormat.js @@ -1,6 +1,3 @@ -/** - * @module structs - */ import { AbstractItem, @@ -13,8 +10,14 @@ import { import * as encoding from 'lib0/encoding.js' import * as decoding from 'lib0/decoding.js' +/** + * @private + */ export const structFormatRefNumber = 4 +/** + * @private + */ export class ItemFormat extends AbstractItem { /** * @param {ID} id @@ -58,6 +61,9 @@ export class ItemFormat extends AbstractItem { } } +/** + * @private + */ export class ItemFormatRef extends AbstractItemRef { /** * @param {decoding.Decoder} decoder diff --git a/src/structs/ItemJSON.js b/src/structs/ItemJSON.js index ceb0def3..42d8e656 100644 --- a/src/structs/ItemJSON.js +++ b/src/structs/ItemJSON.js @@ -1,6 +1,3 @@ -/** - * @module structs - */ import { AbstractItem, @@ -15,8 +12,14 @@ import { import * as encoding from 'lib0/encoding.js' import * as decoding from 'lib0/decoding.js' +/** + * @private + */ export const structJSONRefNumber = 5 +/** + * @private + */ export class ItemJSON extends AbstractItem { /** * @param {ID} id @@ -92,6 +95,9 @@ export class ItemJSON extends AbstractItem { } } +/** + * @private + */ export class ItemJSONRef extends AbstractItemRef { /** * @param {decoding.Decoder} decoder diff --git a/src/structs/ItemString.js b/src/structs/ItemString.js index 24e57f2f..de683ba0 100644 --- a/src/structs/ItemString.js +++ b/src/structs/ItemString.js @@ -1,6 +1,4 @@ -/** - * @module structs - */ + import { AbstractItem, AbstractItemRef, @@ -16,6 +14,9 @@ import * as decoding from 'lib0/decoding.js' export const structStringRefNumber = 6 +/** + * @private + */ export class ItemString extends AbstractItem { /** * @param {ID} id @@ -88,6 +89,9 @@ export class ItemString extends AbstractItem { } } +/** + * @private + */ export class ItemStringRef extends AbstractItemRef { /** * @param {decoding.Decoder} decoder diff --git a/src/structs/ItemType.js b/src/structs/ItemType.js index 5a2cf33c..10a89280 100644 --- a/src/structs/ItemType.js +++ b/src/structs/ItemType.js @@ -1,6 +1,3 @@ -/** - * @module structs - */ import { AbstractItem, @@ -19,10 +16,14 @@ import { import * as encoding from 'lib0/encoding.js' // eslint-disable-line import * as decoding from 'lib0/decoding.js' +/** + * @private + */ export const structTypeRefNumber = 7 /** * @type {Array>} + * @private */ export const typeRefs = [ readYArray, @@ -42,6 +43,9 @@ export const YXmlFragmentRefID = 4 export const YXmlHookRefID = 5 export const YXmlTextRefID = 6 +/** + * @private + */ export class ItemType extends AbstractItem { /** * @param {ID} id @@ -133,6 +137,9 @@ export class ItemType extends AbstractItem { } } +/** + * @private + */ export class ItemTypeRef extends AbstractItemRef { /** * @param {decoding.Decoder} decoder diff --git a/src/types/AbstractType.js b/src/types/AbstractType.js index 76625ab1..42f4736b 100644 --- a/src/types/AbstractType.js +++ b/src/types/AbstractType.js @@ -1,6 +1,3 @@ -/** - * @module structs - */ import { removeEventHandlerListener, @@ -101,6 +98,7 @@ export class AbstractType { /** * @return {AbstractType} + * @private */ _copy () { throw new Error('unimplemented') @@ -108,6 +106,7 @@ export class AbstractType { /** * @param {encoding.Encoder} encoder + * @private */ _write (encoder) { } @@ -125,10 +124,11 @@ export class AbstractType { /** * Creates YEvent and calls all type observers. * Must be implemented by each type. - * @private * * @param {Transaction} transaction * @param {Set} parentSubs Keys changed on this type. `null` if list was modified. + * + * @private */ _callObserver (transaction, parentSubs) { /* skip if no type is specified */ } @@ -178,6 +178,9 @@ export class AbstractType { /** * @param {AbstractType} type * @return {Array} + * + * @private + * @function */ export const typeArrayToArray = type => { const cs = [] @@ -199,6 +202,9 @@ export const typeArrayToArray = type => { * * @param {AbstractType} type * @param {function(any,number,AbstractType):void} f A function to execute on every element of this YArray. + * + * @private + * @function */ export const typeArrayForEach = (type, f) => { let index = 0 @@ -219,6 +225,9 @@ export const typeArrayForEach = (type, f) => { * @param {AbstractType} type * @param {function(C,number,AbstractType):R} f * @return {Array} + * + * @private + * @function */ export const typeArrayMap = (type, f) => { /** @@ -233,7 +242,10 @@ export const typeArrayMap = (type, f) => { /** * @param {AbstractType} type - * @return {{next:function():{done:boolean,value:any|undefined}}} + * @return {IterableIterator} + * + * @private + * @function */ export const typeArrayCreateIterator = type => { let n = type._start @@ -243,6 +255,9 @@ export const typeArrayCreateIterator = type => { let currentContent = null let currentContentIndex = 0 return { + [Symbol.iterator] () { + return this + }, next: () => { // find some content if (currentContent === null) { @@ -284,6 +299,9 @@ export const typeArrayCreateIterator = type => { * @param {AbstractType} type * @param {function(any,number,AbstractType):void} f A function to execute on every element of this YArray. * @param {Snapshot} snapshot + * + * @private + * @function */ export const typeArrayForEachSnapshot = (type, f, snapshot) => { let index = 0 @@ -303,6 +321,9 @@ export const typeArrayForEachSnapshot = (type, f, snapshot) => { * @param {AbstractType} type * @param {number} index * @return {any} + * + * @private + * @function */ export const typeArrayGet = (type, index) => { for (let n = type._start; n !== null; n = n.right) { @@ -320,6 +341,9 @@ export const typeArrayGet = (type, index) => { * @param {AbstractType} parent * @param {AbstractItem?} referenceItem * @param {Array|Array|number|string|ArrayBuffer>} content + * + * @private + * @function */ export const typeArrayInsertGenericsAfter = (transaction, parent, referenceItem, content) => { let left = referenceItem @@ -370,6 +394,9 @@ export const typeArrayInsertGenericsAfter = (transaction, parent, referenceItem, * @param {AbstractType} parent * @param {number} index * @param {Array|Array|number|string|ArrayBuffer>} content + * + * @private + * @function */ export const typeArrayInsertGenerics = (transaction, parent, index, content) => { if (index === 0) { @@ -396,6 +423,9 @@ export const typeArrayInsertGenerics = (transaction, parent, index, content) => * @param {AbstractType} parent * @param {number} index * @param {number} length + * + * @private + * @function */ export const typeArrayDelete = (transaction, parent, index, length) => { if (length === 0) { return } @@ -432,6 +462,9 @@ export const typeArrayDelete = (transaction, parent, index, length) => { * @param {Transaction} transaction * @param {AbstractType} parent * @param {string} key + * + * @private + * @function */ export const typeMapDelete = (transaction, parent, key) => { const c = parent._map.get(key) @@ -445,6 +478,9 @@ export const typeMapDelete = (transaction, parent, key) => { * @param {AbstractType} parent * @param {string} key * @param {Object|number|Array|string|ArrayBuffer|AbstractType} value + * + * @private + * @function */ export const typeMapSet = (transaction, parent, key, value) => { const left = parent._map.get(key) || null @@ -475,6 +511,9 @@ export const typeMapSet = (transaction, parent, key, value) => { * @param {AbstractType} parent * @param {string} key * @return {Object|number|Array|string|ArrayBuffer|AbstractType|undefined} + * + * @private + * @function */ export const typeMapGet = (parent, key) => { const val = parent._map.get(key) @@ -484,6 +523,9 @@ export const typeMapGet = (parent, key) => { /** * @param {AbstractType} parent * @return {Object|number|Array|string|ArrayBuffer|AbstractType|undefined>} + * + * @private + * @function */ export const typeMapGetAll = (parent) => { /** @@ -502,6 +544,9 @@ export const typeMapGetAll = (parent) => { * @param {AbstractType} parent * @param {string} key * @return {boolean} + * + * @private + * @function */ export const typeMapHas = (parent, key) => { const val = parent._map.get(key) @@ -513,6 +558,9 @@ export const typeMapHas = (parent, key) => { * @param {string} key * @param {Snapshot} snapshot * @return {Object|number|Array|string|ArrayBuffer|AbstractType|undefined} + * + * @private + * @function */ export const typeMapGetSnapshot = (parent, key, snapshot) => { let v = parent._map.get(key) || null @@ -525,5 +573,8 @@ export const typeMapGetSnapshot = (parent, key, snapshot) => { /** * @param {Map} map * @return {Iterator<[string,AbstractItem]>} + * + * @private + * @function */ export const createMapIterator = map => iterator.iteratorFilter(map.entries(), entry => !entry[1].deleted) diff --git a/src/types/YArray.js b/src/types/YArray.js index 3156ad4b..6015826b 100644 --- a/src/types/YArray.js +++ b/src/types/YArray.js @@ -1,5 +1,5 @@ /** - * @module types + * @module YArray */ import { @@ -40,12 +40,14 @@ export class YArrayEvent extends YEvent { * A shared Array implementation. * @template T * @extends AbstractType> + * @implements {IterableIterator} */ export class YArray extends AbstractType { constructor () { super() /** * @type {Array?} + * @private */ this._prelimContent = [] } @@ -58,6 +60,7 @@ export class YArray extends AbstractType { * * @param {Y} y The Yjs instance * @param {ItemType} item + * * @private */ _integrate (y, item) { @@ -71,10 +74,11 @@ export class YArray extends AbstractType { } /** * Creates YArrayEvent and calls observers. - * @private * * @param {Transaction} transaction * @param {Set} parentSubs Keys changed on this type. `null` if list was modified. + * + * @private */ _callObserver (transaction, parentSubs) { callTypeObservers(this, transaction, new YArrayEvent(this, transaction)) @@ -131,6 +135,9 @@ export class YArray extends AbstractType { typeArrayForEach(this, f) } + /** + * @return {IterableIterator} + */ [Symbol.iterator] () { return typeArrayCreateIterator(this) } @@ -190,6 +197,7 @@ export class YArray extends AbstractType { /** * @param {encoding.Encoder} encoder + * @private */ _write (encoder) { encoding.writeVarUint(encoder, YArrayRefID) @@ -198,5 +206,8 @@ export class YArray extends AbstractType { /** * @param {decoding.Decoder} decoder + * + * @private + * @function */ export const readYArray = decoder => new YArray() diff --git a/src/types/YMap.js b/src/types/YMap.js index 5206d6f9..23766e7b 100644 --- a/src/types/YMap.js +++ b/src/types/YMap.js @@ -1,5 +1,6 @@ + /** - * @module types + * @module YMap */ import { @@ -41,12 +42,14 @@ export class YMapEvent extends YEvent { * A shared Map implementation. * * @extends AbstractType> + * @implements {IterableIterator} */ export class YMap extends AbstractType { constructor () { super() /** * @type {Map?} + * @private */ this._prelimContent = new Map() } @@ -59,6 +62,7 @@ export class YMap extends AbstractType { * * @param {Y} y The Yjs instance * @param {ItemType} item + * * @private */ _integrate (y, item) { @@ -71,10 +75,11 @@ export class YMap extends AbstractType { } /** * Creates YMapEvent and calls observers. - * @private * * @param {Transaction} transaction * @param {Set} parentSubs Keys changed on this type. `null` if list was modified. + * + * @private */ _callObserver (transaction, parentSubs) { callTypeObservers(this, transaction, new YMapEvent(this, transaction, parentSubs)) @@ -110,12 +115,15 @@ export class YMap extends AbstractType { /** * Returns the value for each element in the YMap Type. * - * @return {Iterator} + * @return {IterableIterator} */ entries () { return iterator.iteratorMap(createMapIterator(this._map), v => v[1].getContent()[0]) } + /** + * @return {IterableIterator} + */ [Symbol.iterator] () { return this.entries() } @@ -177,6 +185,8 @@ export class YMap extends AbstractType { /** * @param {encoding.Encoder} encoder + * + * @private */ _write (encoder) { encoding.writeVarUint(encoder, YMapRefID) @@ -185,5 +195,8 @@ export class YMap extends AbstractType { /** * @param {decoding.Decoder} decoder + * + * @private + * @function */ export const readYMap = decoder => new YMap() diff --git a/src/types/YText.js b/src/types/YText.js index 13e86729..1906daf5 100644 --- a/src/types/YText.js +++ b/src/types/YText.js @@ -1,5 +1,6 @@ + /** - * @module types + * @module YText */ import { @@ -22,7 +23,6 @@ import * as decoding from 'lib0/decoding.js' // eslint-disable-line import * as encoding from 'lib0/encoding.js' /** - * @private * @param {Transaction} transaction * @param {StructStore} store * @param {Map} currentAttributes @@ -30,6 +30,9 @@ import * as encoding from 'lib0/encoding.js' * @param {AbstractItem|null} right * @param {number} count * @return {{left:AbstractItem|null,right:AbstractItem|null,currentAttributes:Map}} + * + * @private + * @function */ const findNextPosition = (transaction, store, currentAttributes, left, right, count) => { while (right !== null && count > 0) { @@ -58,12 +61,14 @@ const findNextPosition = (transaction, store, currentAttributes, left, right, co } /** - * @private * @param {Transaction} transaction * @param {StructStore} store * @param {AbstractType} parent * @param {number} index * @return {{left:AbstractItem|null,right:AbstractItem|null,currentAttributes:Map}} + * + * @private + * @function */ const findPosition = (transaction, store, parent, index) => { let currentAttributes = new Map() @@ -75,13 +80,15 @@ const findPosition = (transaction, store, parent, index) => { /** * Negate applied formats * - * @private * @param {Transaction} transaction * @param {AbstractType} parent * @param {AbstractItem|null} left * @param {AbstractItem|null} right * @param {Map} negatedAttributes * @return {{left:AbstractItem|null,right:AbstractItem|null}} + * + * @private + * @function */ const insertNegatedAttributes = (transaction, parent, left, right, negatedAttributes) => { // check if we really need to remove attributes @@ -109,9 +116,11 @@ const insertNegatedAttributes = (transaction, parent, left, right, negatedAttrib } /** - * @private * @param {Map} currentAttributes * @param {ItemFormat} item + * + * @private + * @function */ const updateCurrentAttributes = (currentAttributes, item) => { const value = item.value @@ -124,12 +133,14 @@ const updateCurrentAttributes = (currentAttributes, item) => { } /** - * @private * @param {AbstractItem|null} left * @param {AbstractItem|null} right * @param {Map} currentAttributes * @param {Object} attributes * @return {{left:AbstractItem|null,right:AbstractItem|null}} + * + * @private + * @function */ const minimizeAttributeChanges = (left, right, currentAttributes, attributes) => { // go right while attributes[right.key] === right.value (or right is deleted) @@ -153,7 +164,6 @@ const minimizeAttributeChanges = (left, right, currentAttributes, attributes) => } /** - * @private * @param {Transaction} transaction * @param {AbstractType} parent * @param {AbstractItem|null} left @@ -161,6 +171,9 @@ const minimizeAttributeChanges = (left, right, currentAttributes, attributes) => * @param {Map} currentAttributes * @param {Object} attributes * @return {{left:AbstractItem|null,right:AbstractItem|null,negatedAttributes:Map}} + * + * @private + * @function **/ const insertAttributes = (transaction, parent, left, right, currentAttributes, attributes) => { const negatedAttributes = new Map() @@ -179,7 +192,6 @@ const insertAttributes = (transaction, parent, left, right, currentAttributes, a } /** - * @private * @param {Transaction} transaction * @param {AbstractType} parent * @param {AbstractItem|null} left @@ -188,6 +200,9 @@ const insertAttributes = (transaction, parent, left, right, currentAttributes, a * @param {string} text * @param {Object} attributes * @return {{left:AbstractItem|null,right:AbstractItem|null}} + * + * @private + * @function **/ const insertText = (transaction, parent, left, right, currentAttributes, text, attributes) => { for (let [key] of currentAttributes) { @@ -210,7 +225,6 @@ const insertText = (transaction, parent, left, right, currentAttributes, text, a } /** - * @private * @param {Transaction} transaction * @param {AbstractType} parent * @param {AbstractItem|null} left @@ -219,6 +233,9 @@ const insertText = (transaction, parent, left, right, currentAttributes, text, a * @param {number} length * @param {Object} attributes * @return {{left:AbstractItem|null,right:AbstractItem|null}} + * + * @private + * @function */ const formatText = (transaction, parent, left, right, currentAttributes, length, attributes) => { const minPos = minimizeAttributeChanges(left, right, currentAttributes, attributes) @@ -264,7 +281,6 @@ const formatText = (transaction, parent, left, right, currentAttributes, length, } /** - * @private * @param {Transaction} transaction * @param {AbstractType} parent * @param {AbstractItem|null} left @@ -272,6 +288,9 @@ const formatText = (transaction, parent, left, right, currentAttributes, length, * @param {Map} currentAttributes * @param {number} length * @return {{left:AbstractItem|null,right:AbstractItem|null}} + * + * @private + * @function */ const deleteText = (transaction, parent, left, right, currentAttributes, length) => { while (length > 0 && right !== null) { @@ -326,8 +345,6 @@ const deleteText = (transaction, parent, left, right, currentAttributes, length) /** * Event that describes the changes on a YText type. - * - * @private */ class YTextEvent extends YEvent { /** @@ -337,6 +354,7 @@ class YTextEvent extends YEvent { constructor (ytext, transaction) { super(ytext, transaction) /** + * @private * @type {Array<{delete:number|undefined,retain:number|undefined,insert:string|undefined,attributes:Object}>|null} */ this._delta = null @@ -558,6 +576,7 @@ export class YText extends AbstractType { super() /** * @type {Array?} + * @private */ this._prelimContent = string !== undefined ? [string] : [] } @@ -569,6 +588,8 @@ export class YText extends AbstractType { /** * @param {Y} y * @param {ItemType} item + * + * @private */ _integrate (y, item) { super._integrate(y, item) @@ -579,10 +600,11 @@ export class YText extends AbstractType { /** * Creates YTextEvent and calls observers. - * @private * * @param {Transaction} transaction * @param {Set} parentSubs Keys changed on this type. `null` if list was modified. + * + * @private */ _callObserver (transaction, parentSubs) { callTypeObservers(this, transaction, new YTextEvent(this, transaction)) @@ -847,6 +869,8 @@ export class YText extends AbstractType { /** * @param {encoding.Encoder} encoder + * + * @private */ _write (encoder) { encoding.writeVarUint(encoder, YTextRefID) @@ -856,5 +880,8 @@ export class YText extends AbstractType { /** * @param {decoding.Decoder} decoder * @return {YText} + * + * @private + * @function */ export const readYText = decoder => new YText() diff --git a/src/types/YXmlElement.js b/src/types/YXmlElement.js index 32027380..85d326b5 100644 --- a/src/types/YXmlElement.js +++ b/src/types/YXmlElement.js @@ -1,5 +1,5 @@ /** - * @module types + * @module YXml */ import { @@ -50,6 +50,7 @@ import * as decoding from 'lib0/decoding.js' * Can be created with {@link YXmlFragment#createTreeWalker} * * @public + * @implements {IterableIterator} */ export class YXmlTreeWalker { /** @@ -66,6 +67,7 @@ export class YXmlTreeWalker { this._currentNode = root._start this._firstCall = true } + [Symbol.iterator] () { return this } @@ -250,10 +252,12 @@ export class YXmlElement extends YXmlFragment { this.nodeName = nodeName.toUpperCase() /** * @type {Array|null} + * @private */ this._prelimContent = [] /** * @type {Map|null} + * @private */ this._prelimAttrs = new Map() } @@ -471,10 +475,16 @@ export class YXmlElement extends YXmlFragment { /** * @param {decoding.Decoder} decoder * @return {YXmlElement} + * + * @private + * @function */ export const readYXmlElement = decoder => new YXmlElement(decoding.readVarString(decoder)) /** * @param {decoding.Decoder} decoder * @return {YXmlFragment} + * + * @private + * @function */ export const readYXmlFragment = decoder => new YXmlFragment() diff --git a/src/types/YXmlEvent.js b/src/types/YXmlEvent.js index 38f4b727..c41ba3d4 100644 --- a/src/types/YXmlEvent.js +++ b/src/types/YXmlEvent.js @@ -1,6 +1,3 @@ -/** - * @module types - */ import { YEvent, @@ -9,8 +6,6 @@ import { /** * An Event that describes changes on a YXml Element or Yxml Fragment - * - * @protected */ export class YXmlEvent extends YEvent { /** @@ -22,14 +17,10 @@ export class YXmlEvent extends YEvent { */ constructor (target, subs, transaction) { super(target, transaction) - /** - * The transaction instance for the computed change. - * @type {Transaction} - */ - this._transaction = transaction /** * Whether the children changed. * @type {Boolean} + * @private */ this.childListChanged = false /** diff --git a/src/types/YXmlHook.js b/src/types/YXmlHook.js index a16262be..bd7f2564 100644 --- a/src/types/YXmlHook.js +++ b/src/types/YXmlHook.js @@ -1,6 +1,3 @@ -/** - * @module types - */ import { YMap, @@ -20,6 +17,9 @@ export class YXmlHook extends YMap { */ constructor (hookName) { super() + /** + * @type {string} + */ this.hookName = hookName } @@ -82,6 +82,9 @@ export class YXmlHook extends YMap { /** * @param {decoding.Decoder} decoder * @return {YXmlHook} + * + * @private + * @function */ export const readYXmlHook = decoder => new YXmlHook(decoding.readVarString(decoder)) diff --git a/src/types/YXmlText.js b/src/types/YXmlText.js index f53d0023..09612251 100644 --- a/src/types/YXmlText.js +++ b/src/types/YXmlText.js @@ -1,6 +1,3 @@ -/** - * @module types - */ import { YText, YXmlTextRefID } from '../internals.js' @@ -36,6 +33,8 @@ export class YXmlText extends YText { } /** * @param {encoding.Encoder} encoder + * + * @private */ _write (encoder) { encoding.writeVarUint(encoder, YXmlTextRefID) @@ -45,5 +44,8 @@ export class YXmlText extends YText { /** * @param {decoding.Decoder} decoder * @return {YXmlText} + * + * @private + * @function */ export const readYXmlText = decoder => new YXmlText() diff --git a/src/utils/DeleteSet.js b/src/utils/DeleteSet.js index 44417d19..a7340e8c 100644 --- a/src/utils/DeleteSet.js +++ b/src/utils/DeleteSet.js @@ -11,6 +11,9 @@ import * as map from 'lib0/map.js' import * as encoding from 'lib0/encoding.js' import * as decoding from 'lib0/decoding.js' +/** + * @private + */ class DeleteItem { /** * @param {number} clock @@ -35,11 +38,13 @@ class DeleteItem { * - We do not create a DeleteSet when we send a sync message. The DeleteSet message is created directly from StructStore * - We read a DeleteSet as part of a sync/update message. In this case the DeleteSet is already sorted and merged. * + * @private */ export class DeleteSet { constructor () { /** * @type {Map>} + * @private */ this.clients = new Map() } @@ -49,6 +54,9 @@ export class DeleteSet { * @param {Array} dis * @param {number} clock * @return {number|null} + * + * @private + * @function */ export const findIndexDS = (dis, clock) => { let left = 0 @@ -73,6 +81,9 @@ export const findIndexDS = (dis, clock) => { * @param {DeleteSet} ds * @param {ID} id * @return {boolean} + * + * @private + * @function */ export const isDeleted = (ds, id) => { const dis = ds.clients.get(id.client) @@ -81,6 +92,9 @@ export const isDeleted = (ds, id) => { /** * @param {DeleteSet} ds + * + * @private + * @function */ export const sortAndMergeDeleteSet = ds => { ds.clients.forEach(dels => { @@ -110,6 +124,9 @@ export const sortAndMergeDeleteSet = ds => { * @param {DeleteSet} ds * @param {ID} id * @param {number} length + * + * @private + * @function */ export const addToDeleteSet = (ds, id, length) => { map.setIfUndefined(ds.clients, id.client, () => []).push(new DeleteItem(id.clock, length)) @@ -118,6 +135,9 @@ export const addToDeleteSet = (ds, id, length) => { /** * @param {StructStore} ss * @return {DeleteSet} Merged and sorted DeleteSet + * + * @private + * @function */ export const createDeleteSetFromStructStore = ss => { const ds = new DeleteSet() @@ -149,6 +169,9 @@ export const createDeleteSetFromStructStore = ss => { /** * @param {encoding.Encoder} encoder * @param {DeleteSet} ds + * + * @private + * @function */ export const writeDeleteSet = (encoder, ds) => { encoding.writeVarUint(encoder, ds.clients.size) @@ -168,6 +191,9 @@ export const writeDeleteSet = (encoder, ds) => { * @param {decoding.Decoder} decoder * @param {Transaction} transaction * @param {StructStore} store + * + * @private + * @function */ export const readDeleteSet = (decoder, transaction, store) => { const unappliedDS = new DeleteSet() diff --git a/src/utils/EventHandler.js b/src/utils/EventHandler.js index f366338a..427430e9 100644 --- a/src/utils/EventHandler.js +++ b/src/utils/EventHandler.js @@ -4,6 +4,8 @@ import * as f from 'lib0/function.js' * General event handler implementation. * * @template ARG0, ARG1 + * + * @private */ export class EventHandler { constructor () { @@ -17,6 +19,9 @@ export class EventHandler { /** * @template ARG0,ARG1 * @returns {EventHandler} + * + * @private + * @function */ export const createEventHandler = () => new EventHandler() @@ -27,6 +32,9 @@ export const createEventHandler = () => new EventHandler() * @template ARG0,ARG1 * @param {EventHandler} eventHandler * @param {function(ARG0,ARG1):void} f The event handler. + * + * @private + * @function */ export const addEventHandlerListener = (eventHandler, f) => eventHandler.l.push(f) @@ -38,6 +46,9 @@ export const addEventHandlerListener = (eventHandler, f) => * @param {EventHandler} eventHandler * @param {function(ARG0,ARG1):void} f The event handler that was added with * {@link EventHandler#addEventListener} + * + * @private + * @function */ export const removeEventHandlerListener = (eventHandler, f) => { eventHandler.l = eventHandler.l.filter(g => f !== g) @@ -47,6 +58,9 @@ export const removeEventHandlerListener = (eventHandler, f) => { * Removes all event listeners. * @template ARG0,ARG1 * @param {EventHandler} eventHandler + * + * @private + * @function */ export const removeAllEventHandlerListeners = eventHandler => { eventHandler.l.length = 0 @@ -59,6 +73,9 @@ export const removeAllEventHandlerListeners = eventHandler => { * @template ARG0,ARG1 * @param {EventHandler} eventHandler * @param {[ARG0,ARG1]} args + * + * @private + * @function */ export const callEventHandlerListeners = (eventHandler, args) => f.callAll(eventHandler.l, args) diff --git a/src/utils/ID.js b/src/utils/ID.js index e2229d23..76f0cd28 100644 --- a/src/utils/ID.js +++ b/src/utils/ID.js @@ -1,6 +1,3 @@ -/** - * @module utils - */ import { AbstractType } from '../internals' // eslint-disable-line @@ -41,18 +38,26 @@ export class ID { * @param {ID | null} a * @param {ID | null} b * @return {boolean} + * + * @function */ export const compareIDs = (a, b) => a === b || (a !== null && b !== null && a.client === b.client && a.clock === b.clock) /** * @param {number} client * @param {number} clock + * + * @private + * @function */ export const createID = (client, clock) => new ID(client, clock) /** * @param {encoding.Encoder} encoder * @param {ID} id + * + * @private + * @function */ export const writeID = (encoder, id) => { encoding.writeVarUint(encoder, id.client) @@ -66,6 +71,9 @@ export const writeID = (encoder, id) => { * * @param {decoding.Decoder} decoder * @return {ID} + * + * @private + * @function */ export const readID = decoder => createID(decoding.readVarUint(decoder), decoding.readVarUint(decoder)) @@ -77,6 +85,9 @@ export const readID = decoder => * * @param {AbstractType} type * @return {string} + * + * @private + * @function */ export const findRootTypeKey = type => { // @ts-ignore _y must be defined, otherwise unexpected case diff --git a/src/utils/Snapshot.js b/src/utils/Snapshot.js index 941be3c6..72c0c061 100644 --- a/src/utils/Snapshot.js +++ b/src/utils/Snapshot.js @@ -10,17 +10,34 @@ export class Snapshot { * @param {DeleteSet} ds delete store * @param {Map} sm state map * @param {Map} userMap + * @private */ constructor (ds, sm, userMap) { + /** + * @type {DeleteSet} + * @private + */ this.ds = new DeleteSet() + /** + * State Map + * @type {Map} + * @private + */ this.sm = sm + /** + * @type {Map} + * @private + */ this.userMap = userMap } } /** * @param {AbstractItem} item - * @param {Snapshot} [snapshot] + * @param {Snapshot|undefined} snapshot + * + * @protected + * @function */ export const isVisible = (item, snapshot) => snapshot === undefined ? !item.deleted : ( snapshot.sm.has(item.id.client) && (snapshot.sm.get(item.id.client) || 0) > item.id.clock && !isDeleted(snapshot.ds, item.id) diff --git a/src/utils/StructStore.js b/src/utils/StructStore.js index da28168f..7f9b8e1c 100644 --- a/src/utils/StructStore.js +++ b/src/utils/StructStore.js @@ -13,6 +13,7 @@ export class StructStore { constructor () { /** * @type {Map>} + * @private */ this.clients = new Map() /** @@ -22,16 +23,19 @@ export class StructStore { * slow in Chrome for arrays with more than 100k elements * @see tryResumePendingStructRefs * @type {Map}>} + * @private */ this.pendingClientsStructRefs = new Map() /** * Stack of pending structs waiting for struct dependencies * Maximum length of stack is structReaders.size * @type {Array} + * @private */ this.pendingStack = [] /** * @type {Array} + * @private */ this.pendingDeleteReaders = [] } @@ -43,6 +47,9 @@ export class StructStore { * * @param {StructStore} store * @return {Map} + * + * @public + * @function */ export const getStates = store => { const sm = new Map() @@ -56,6 +63,10 @@ export const getStates = store => { /** * @param {StructStore} store * @param {number} client + * @return {number} + * + * @public + * @function */ export const getState = (store, client) => { const structs = store.clients.get(client) @@ -68,6 +79,9 @@ export const getState = (store, client) => { /** * @param {StructStore} store + * + * @private + * @function */ export const integretyCheck = store => { store.clients.forEach(structs => { @@ -84,6 +98,9 @@ export const integretyCheck = store => { /** * @param {StructStore} store * @param {AbstractStruct} struct + * + * @private + * @function */ export const addStruct = (store, struct) => { let structs = store.clients.get(struct.id.client) @@ -104,7 +121,9 @@ export const addStruct = (store, struct) => { * @param {Array} structs * @param {number} clock * @return {number} + * * @private + * @function */ export const findIndexSS = (structs, clock) => { let left = 0 @@ -133,7 +152,9 @@ export const findIndexSS = (structs, clock) => { * @param {StructStore} store * @param {ID} id * @return {AbstractStruct} + * * @private + * @function */ export const find = (store, id) => { /** @@ -150,6 +171,9 @@ export const find = (store, id) => { * @param {StructStore} store * @param {ID} id * @return {AbstractItem} + * + * @private + * @function */ // @ts-ignore export const getItem = (store, id) => find(store, id) @@ -160,6 +184,9 @@ export const getItem = (store, id) => find(store, id) * @param {StructStore} store * @param {ID} id * @return {ItemType} + * + * @private + * @function */ // @ts-ignore export const getItemType = (store, id) => find(store, id) @@ -173,6 +200,7 @@ export const getItemType = (store, id) => find(store, id) * @return {AbstractItem} * * @private + * @function */ export const getItemCleanStart = (transaction, store, id) => { /** @@ -201,6 +229,7 @@ export const getItemCleanStart = (transaction, store, id) => { * @return {AbstractItem} * * @private + * @function */ export const getItemCleanEnd = (transaction, store, id) => { /** @@ -221,6 +250,9 @@ export const getItemCleanEnd = (transaction, store, id) => { * @param {StructStore} store * @param {AbstractStruct} struct * @param {AbstractStruct} newStruct + * + * @private + * @function */ export const replaceStruct = (store, struct, newStruct) => { /** @@ -235,6 +267,9 @@ export const replaceStruct = (store, struct, newStruct) => { * @param {StructStore} store * @param {ID} id * @return {boolean} + * + * @private + * @function */ export const exists = (store, id) => id.clock < getState(store, id.client) @@ -243,6 +278,9 @@ export const exists = (store, id) => id.clock < getState(store, id.client) * * @param {decoding.Decoder} decoder * @return {Map} + * + * @private + * @function */ export const readStatesAsMap = decoder => { const ss = new Map() @@ -260,6 +298,9 @@ export const readStatesAsMap = decoder => { * * @param {encoding.Encoder} encoder * @param {StructStore} store + * + * @private + * @function */ export const writeStates = (encoder, store) => { encoding.writeVarUint(encoder, store.clients.size) diff --git a/src/utils/Transaction.js b/src/utils/Transaction.js index 7c867ce8..bdb66cf2 100644 --- a/src/utils/Transaction.js +++ b/src/utils/Transaction.js @@ -1,6 +1,3 @@ -/** - * @module utils - */ import { getState, @@ -43,6 +40,7 @@ import * as math from 'lib0/math.js' * map.set('b', 1) * }) // => "change triggered" * + * @public */ export class Transaction { /** @@ -84,15 +82,18 @@ export class Transaction { this.changedParentTypes = new Map() /** * @type {encoding.Encoder|null} + * @private */ this._updateMessage = null /** * @type {Set} + * @private */ this._mergeStructs = new Set() } /** * @type {encoding.Encoder|null} + * @public */ get updateMessage () { // only create if content was added in transaction (state or ds changed) @@ -109,6 +110,9 @@ export class Transaction { /** * @param {Transaction} transaction + * + * @private + * @function */ export const nextID = transaction => { const y = transaction.y @@ -120,6 +124,9 @@ export const nextID = transaction => { * * @param {Y} y * @param {function(Transaction):void} f + * + * @private + * @function */ export const transact = (y, f) => { let initialCall = false diff --git a/src/utils/UndoManager.js b/src/utils/UndoManager.js index 926602ed..ed3f4ace 100644 --- a/src/utils/UndoManager.js +++ b/src/utils/UndoManager.js @@ -6,6 +6,9 @@ import { transact } from '../internals.js' +/** + * @private + */ class ReverseOperation { constructor (y, transaction, bindingInfos) { this.created = new Date() @@ -31,6 +34,10 @@ class ReverseOperation { } } +/** + * @private + * @function + */ function applyReverseOperation (y, scope, reverseBuffer) { let performedUndo = false let undoOp = null @@ -90,6 +97,9 @@ function applyReverseOperation (y, scope, reverseBuffer) { /** * Saves a history of locally applied operations. The UndoManager handles the * undoing and redoing of locally created changes. + * + * @private + * @function */ export class UndoManager { /** @@ -156,6 +166,9 @@ export class UndoManager { /** * Enforce that the next change is created as a separate item in the undo stack + * + * @private + * @function */ flushChanges () { this._lastTransactionWasUndo = true @@ -163,6 +176,9 @@ export class UndoManager { /** * Undo the last locally created change. + * + * @private + * @function */ undo () { this._undoing = true @@ -173,6 +189,9 @@ export class UndoManager { /** * Redo the last locally created change. + * + * @private + * @function */ redo () { this._redoing = true diff --git a/src/utils/Y.js b/src/utils/Y.js index 080a7c49..fe49b82d 100644 --- a/src/utils/Y.js +++ b/src/utils/Y.js @@ -1,3 +1,7 @@ +/** + * @module Y + */ + import { StructStore, AbstractType, @@ -10,7 +14,6 @@ import { } from '../internals.js' import { Observable } from 'lib0/observable.js' -import * as error from 'lib0/error.js' import * as random from 'lib0/random.js' import * as map from 'lib0/map.js' @@ -20,11 +23,10 @@ import * as map from 'lib0/map.js' */ export class Y extends Observable { /** - * @param {Object} [conf] configuration + * @param {Object|undefined} conf configuration */ constructor (conf = {}) { super() - this.gcEnabled = conf.gc || false this.clientID = random.uint32() /** * @type {Map>} @@ -33,19 +35,10 @@ export class Y extends Observable { this.store = new StructStore() /** * @type {Transaction | null} + * @private */ this._transaction = null } - /** - * @type {Transaction} - */ - get transaction () { - const t = this._transaction - if (t === null) { - throw error.create('All changes must happen inside a transaction') - } - return t - } /** * Changes that happen inside of a transaction are bundled. This means that * the observer fires _after_ the transaction is finished and that all changes @@ -53,6 +46,8 @@ export class Y extends Observable { * other peers. * * @param {function(Transaction):void} f The function that should be executed as a transaction + * + * @public */ transact (f) { transact(this, f) @@ -80,6 +75,8 @@ export class Y extends Observable { * @param {string} name * @param {Function} TypeConstructor The constructor of the type definition * @return {AbstractType} The created type. Constructed with TypeConstructor + * + * @public */ get (name, TypeConstructor = AbstractType) { const type = map.setIfUndefined(this.share, name, () => { @@ -108,6 +105,8 @@ export class Y extends Observable { * @template T * @param {string} name * @return {YArray} + * + * @public */ getArray (name) { // @ts-ignore @@ -116,6 +115,8 @@ export class Y extends Observable { /** * @param {string} name * @return {YText} + * + * @public */ getText (name) { // @ts-ignore @@ -124,6 +125,8 @@ export class Y extends Observable { /** * @param {string} name * @return {YMap} + * + * @public */ getMap (name) { // @ts-ignore @@ -132,13 +135,17 @@ export class Y extends Observable { /** * @param {string} name * @return {YXmlFragment} + * + * @public */ getXmlFragment (name) { // @ts-ignore return this.get(name, YXmlFragment) } /** - * Disconnect from the room, and destroy all traces of this Yjs instance. + * Emit `destroy` event and unregister all event handlers. + * + * @protected */ destroy () { this.emit('destroyed', [true]) diff --git a/src/utils/YEvent.js b/src/utils/YEvent.js index 7ee2179f..63435563 100644 --- a/src/utils/YEvent.js +++ b/src/utils/YEvent.js @@ -1,13 +1,9 @@ import { isDeleted, - AbstractItem, AbstractType, Transaction, AbstractStruct // eslint-disable-line + AbstractType, Transaction, AbstractStruct // eslint-disable-line } from '../internals.js' -/** - * @module utils - */ - /** * YEvent describes the changes on a YType. */ @@ -84,6 +80,9 @@ export class YEvent { * @param {AbstractType} parent * @param {AbstractType} child target * @return {Array} Path to the target + * + * @private + * @function */ const getPathTo = (parent, child) => { const path = [] diff --git a/src/utils/structEncoding.js b/src/utils/encoding.js similarity index 95% rename from src/utils/structEncoding.js rename to src/utils/encoding.js index a82a865e..73658685 100644 --- a/src/utils/structEncoding.js +++ b/src/utils/encoding.js @@ -1,4 +1,8 @@ +/** + * @module encoding + */ + import { findIndexSS, exists, @@ -26,9 +30,8 @@ import * as decoding from 'lib0/decoding.js' import * as binary from 'lib0/binary.js' /** - * @typedef {Map} StateMap + * @private */ - export const structRefs = [ GCRef, ItemBinaryRef, @@ -45,6 +48,8 @@ export const structRefs = [ * @param {Array} structs All structs by `client` * @param {number} client * @param {number} clock write structs starting with `ID(client,clock)` + * + * @function */ const writeStructs = (encoder, structs, client, clock) => { // write first id @@ -65,6 +70,9 @@ const writeStructs = (encoder, structs, client, clock) => { * @param {number} numOfStructs * @param {ID} nextID * @return {Array} + * + * @private + * @function */ const readStructRefs = (decoder, numOfStructs, nextID) => { /** @@ -83,7 +91,10 @@ const readStructRefs = (decoder, numOfStructs, nextID) => { /** * @param {encoding.Encoder} encoder * @param {StructStore} store - * @param {StateMap} _sm + * @param {Map} _sm + * + * @private + * @function */ export const writeClientsStructs = (encoder, store, _sm) => { // we filter all valid _sm entries into sm @@ -110,6 +121,9 @@ export const writeClientsStructs = (encoder, store, _sm) => { /** * @param {decoding.Decoder} decoder The decoder object to read data from. * @return {Map>} + * + * @private + * @function */ export const readClientsStructRefs = decoder => { /** @@ -148,6 +162,8 @@ export const readClientsStructRefs = decoder => { * @param {Transaction} transaction * @param {StructStore} store * + * @private + * @function */ const resumeStructIntegration = (transaction, store) => { const stack = store.pendingStack @@ -216,6 +232,9 @@ const resumeStructIntegration = (transaction, store) => { /** * @param {Transaction} transaction * @param {StructStore} store + * + * @private + * @function */ export const tryResumePendingDeleteReaders = (transaction, store) => { const pendingReaders = store.pendingDeleteReaders @@ -225,31 +244,28 @@ export const tryResumePendingDeleteReaders = (transaction, store) => { } } -/** - * @param {Map,i:number}>} pendingClientsStructRefs - * @param {number} client - * @param {Array} refs - */ -const setPendingClientsStructRefs = (pendingClientsStructRefs, client, refs) => { - pendingClientsStructRefs.set(client, { refs, i: 0 }) -} - /** * @param {encoding.Encoder} encoder * @param {Transaction} transaction + * + * @private + * @function */ export const writeStructsFromTransaction = (encoder, transaction) => writeClientsStructs(encoder, transaction.y.store, transaction.beforeState) /** * @param {StructStore} store * @param {Map>} clientsStructsRefs + * + * @private + * @function */ const mergeReadStructsIntoPendingReads = (store, clientsStructsRefs) => { const pendingClientsStructRefs = store.pendingClientsStructRefs for (const [client, structRefs] of clientsStructsRefs) { const pendingStructRefs = pendingClientsStructRefs.get(client) if (pendingStructRefs === undefined) { - setPendingClientsStructRefs(pendingClientsStructRefs, client, structRefs) + pendingClientsStructRefs.set(client, { refs: structRefs, i: 0 }) } else { // merge into existing structRefs const merged = pendingStructRefs.i > 0 ? pendingStructRefs.refs.slice(pendingStructRefs.i) : pendingStructRefs.refs @@ -272,6 +288,7 @@ const mergeReadStructsIntoPendingReads = (store, clientsStructsRefs) => { * @param {StructStore} store * * @private + * @function */ export const readStructs = (decoder, transaction, store) => { const clientsStructRefs = readClientsStructRefs(decoder) @@ -284,6 +301,8 @@ export const readStructs = (decoder, transaction, store) => { * @param {decoding.Decoder} decoder * @param {Transaction} transaction * @param {StructStore} store + * + * @function */ export const readModel = (decoder, transaction, store) => { readStructs(decoder, transaction, store) @@ -294,6 +313,8 @@ export const readModel = (decoder, transaction, store) => { * @param {encoding.Encoder} encoder * @param {StructStore} store * @param {Map} [targetState] The state of the target that receives the update. Leave empty to write all known structs + * + * @function */ export const writeModel = (encoder, store, targetState = new Map()) => { writeClientsStructs(encoder, store, targetState) diff --git a/src/utils/isParentOf.js b/src/utils/isParentOf.js index 808212c7..083eb4c7 100644 --- a/src/utils/isParentOf.js +++ b/src/utils/isParentOf.js @@ -1,6 +1,3 @@ -/** - * @module utils - */ import { AbstractType } from '../internals.js' // eslint-disable-line @@ -11,7 +8,8 @@ import { AbstractType } from '../internals.js' // eslint-disable-line * @param {AbstractType} child * @return {Boolean} Whether `parent` is a parent of `child`. * - * @public + * @private + * @function */ export const isParentOf = (parent, child) => { while (child._item !== null) { diff --git a/src/utils/relativePosition.js b/src/utils/relativePosition.js index 2d511619..1e4be658 100644 --- a/src/utils/relativePosition.js +++ b/src/utils/relativePosition.js @@ -1,3 +1,6 @@ +/** + * @module RelativePosition + */ import { find, @@ -79,6 +82,8 @@ export class RelativePosition { /** * @param {Object} json * @return {RelativePosition} + * + * @function */ export const createRelativePositionFromJSON = json => new RelativePosition(json.type == null ? null : createID(json.type.client, json.type.clock), json.tname || null, json.item == null ? null : createID(json.item.client, json.item.clock)) @@ -102,12 +107,16 @@ export class AbsolutePosition { /** * @param {AbstractType} type * @param {number} offset + * + * @function */ export const createAbsolutePosition = (type, offset) => new AbsolutePosition(type, offset) /** * @param {AbstractType} type * @param {ID|null} item + * + * @function */ export const createRelativePosition = (type, item) => { let typeid = null @@ -126,6 +135,8 @@ export const createRelativePosition = (type, item) => { * @param {AbstractType} type The base type (e.g. YText or YArray). * @param {number} offset The absolute position. * @return {RelativePosition} + * + * @function */ export const createRelativePositionByOffset = (type, offset) => { let t = type._start @@ -145,6 +156,8 @@ export const createRelativePositionByOffset = (type, offset) => { /** * @param {encoding.Encoder} encoder * @param {RelativePosition} rpos + * + * @function */ export const writeRelativePosition = (encoder, rpos) => { const { type, tname, item } = rpos @@ -170,6 +183,8 @@ export const writeRelativePosition = (encoder, rpos) => { * @param {Y} y * @param {StructStore} store * @return {RelativePosition|null} + * + * @function */ export const readRelativePosition = (decoder, y, store) => { let type = null @@ -196,6 +211,8 @@ export const readRelativePosition = (decoder, y, store) => { * @param {RelativePosition} rpos * @param {Y} y * @return {AbsolutePosition|null} + * + * @function */ export const toAbsolutePosition = (rpos, y) => { const store = y.store @@ -244,6 +261,8 @@ export const toAbsolutePosition = (rpos, y) => { * @param {Y} y The Yjs instance in which to query for the absolute position. * @return {RelativePosition} The absolute position in the Yjs model * (type + offset). + * + * @function */ export const toRelativePosition = (apos, y) => { const type = apos.type @@ -268,6 +287,8 @@ export const toRelativePosition = (apos, y) => { /** * @param {RelativePosition|null} a * @param {RelativePosition|null} b + * + * @function */ export const compareRelativePositions = (a, b) => a === b || ( a !== null && b !== null && a.tname === b.tname && (