improve jsdoc comments

README.v13.md

@@ -74,9 +74,7 @@ Yjs does not hava any dependencies. Install this package with your favorite pack
 npm i yjs
 ```
 
-##### Tutorial
+##### Quickstart
-
-In this *short* tutorial I will give an overview of the basic concepts in Yjs.
 
 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. 

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'

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<any>} 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<YEvent>?,parentSub:string?}}
+ *
+ * @private
+ * @function
  */
 export const computeItemParams = (transaction, store, leftid, rightid, parentid, parentSub, parentYKey) => {
   const left = leftid === null ? null : getItemCleanEnd(transaction, store, leftid)

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

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

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

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

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

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

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

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

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<function(decoding.Decoder):AbstractType<any>>}
+ * @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

src/types/AbstractType.js

@@ -1,6 +1,3 @@
-/**
- * @module structs
- */
 
 import {
   removeEventHandlerListener,
@@ -101,6 +98,7 @@ export class AbstractType {
 
   /**
    * @return {AbstractType<EventType>}
+   * @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<null|string>} 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<any>} type
  * @return {Array<any>}
+ *
+ * @private
+ * @function
  */
 export const typeArrayToArray = type => {
   const cs = []
@@ -199,6 +202,9 @@ export const typeArrayToArray = type => {
  *
  * @param {AbstractType<any>} type
  * @param {function(any,number,AbstractType<any>):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<any>} type
  * @param {function(C,number,AbstractType<any>):R} f
  * @return {Array<R>}
+ *
+ * @private
+ * @function
  */
 export const typeArrayMap = (type, f) => {
   /**
@@ -233,7 +242,10 @@ export const typeArrayMap = (type, f) => {
 
 /**
  * @param {AbstractType<any>} type
- * @return {{next:function():{done:boolean,value:any|undefined}}}
+ * @return {IterableIterator<any>}
+ *
+ * @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<any>} type
  * @param {function(any,number,AbstractType<any>):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<any>} 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<any>} parent
  * @param {AbstractItem?} referenceItem
  * @param {Array<Object<string,any>|Array<any>|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<any>} parent
  * @param {number} index
  * @param {Array<Object<string,any>|Array<any>|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<any>} 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<any>} 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<any>} parent
  * @param {string} key
  * @param {Object|number|Array<any>|string|ArrayBuffer|AbstractType<any>} 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<any>} parent
  * @param {string} key
  * @return {Object<string,any>|number|Array<any>|string|ArrayBuffer|AbstractType<any>|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<any>} parent
  * @return {Object<string,Object<string,any>|number|Array<any>|string|ArrayBuffer|AbstractType<any>|undefined>}
+ *
+ * @private
+ * @function
  */
 export const typeMapGetAll = (parent) => {
   /**
@@ -502,6 +544,9 @@ export const typeMapGetAll = (parent) => {
  * @param {AbstractType<any>} 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<string,any>|number|Array<any>|string|ArrayBuffer|AbstractType<any>|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<string,AbstractItem>} map
  * @return {Iterator<[string,AbstractItem]>}
+ *
+ * @private
+ * @function
  */
 export const createMapIterator = map => iterator.iteratorFilter(map.entries(), entry => !entry[1].deleted)

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<YArrayEvent<T>>
+ * @implements {IterableIterator<T>}
  */
 export class YArray extends AbstractType {
   constructor () {
     super()
     /**
      * @type {Array<any>?}
+     * @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<null|string>} 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<T>}
+   */
   [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()

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<YMapEvent<T>>
+ * @implements {IterableIterator}
  */
 export class YMap extends AbstractType {
   constructor () {
     super()
     /**
      * @type {Map<string,any>?}
+     * @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<null|string>} 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<T>}
+   * @return {IterableIterator<T>}
    */
   entries () {
     return iterator.iteratorMap(createMapIterator(this._map), v => v[1].getContent()[0])
   }
 
+  /**
+   * @return {IterableIterator<T>}
+   */
   [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()

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<string,any>} 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<string,any>}}
+ *
+ * @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<any>} parent
  * @param {number} index
  * @return {{left:AbstractItem|null,right:AbstractItem|null,currentAttributes:Map<string,any>}}
+ *
+ * @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<any>} parent
  * @param {AbstractItem|null} left
  * @param {AbstractItem|null} right
  * @param {Map<string,any>} 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<string,any>} 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<string,any>} currentAttributes
  * @param {Object<string,any>} 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<any>} parent
  * @param {AbstractItem|null} left
@@ -161,6 +171,9 @@ const minimizeAttributeChanges = (left, right, currentAttributes, attributes) =>
  * @param {Map<string,any>} currentAttributes
  * @param {Object<string,any>} attributes
  * @return {{left:AbstractItem|null,right:AbstractItem|null,negatedAttributes:Map<string,any>}}
+ *
+ * @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<any>} parent
  * @param {AbstractItem|null} left
@@ -188,6 +200,9 @@ const insertAttributes = (transaction, parent, left, right, currentAttributes, a
  * @param {string} text
  * @param {Object<string,any>} 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<any>} parent
  * @param {AbstractItem|null} left
@@ -219,6 +233,9 @@ const insertText = (transaction, parent, left, right, currentAttributes, text, a
  * @param {number} length
  * @param {Object<string,any>} 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<any>} parent
  * @param {AbstractItem|null} left
@@ -272,6 +288,9 @@ const formatText = (transaction, parent, left, right, currentAttributes, length,
  * @param {Map<string,any>} 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<string,any>}>|null}
      */
     this._delta = null
@@ -558,6 +576,7 @@ export class YText extends AbstractType {
     super()
     /**
      * @type {Array<string>?}
+     * @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<null|string>} 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()

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<any>|null}
+     * @private
      */
     this._prelimContent = []
     /**
      * @type {Map<string, any>|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()

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
     /**

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))

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()

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<number,Array<DeleteItem>>}
+     * @private
      */
     this.clients = new Map()
   }
@@ -49,6 +54,9 @@ export class DeleteSet {
  * @param {Array<DeleteItem>} 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()

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<ARG0,ARG1>}
+ *
+ * @private
+ * @function
  */
 export const createEventHandler = () => new EventHandler()
 
@@ -27,6 +32,9 @@ export const createEventHandler = () => new EventHandler()
  * @template ARG0,ARG1
  * @param {EventHandler<ARG0,ARG1>} 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<ARG0,ARG1>} 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<ARG0,ARG1>} eventHandler
+ *
+ * @private
+ * @function
  */
 export const removeAllEventHandlerListeners = eventHandler => {
   eventHandler.l.length = 0
@@ -59,6 +73,9 @@ export const removeAllEventHandlerListeners = eventHandler => {
  * @template ARG0,ARG1
  * @param {EventHandler<ARG0,ARG1>} eventHandler
  * @param {[ARG0,ARG1]} args
+ *
+ * @private
+ * @function
  */
 export const callEventHandlerListeners = (eventHandler, args) =>
   f.callAll(eventHandler.l, args)

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<any>} type
  * @return {string}
+ *
+ * @private
+ * @function
  */
 export const findRootTypeKey = type => {
   // @ts-ignore _y must be defined, otherwise unexpected case

src/utils/Snapshot.js

@@ -10,17 +10,34 @@ export class Snapshot {
    * @param {DeleteSet} ds delete store
    * @param {Map<number,number>} sm state map
    * @param {Map<number,string>} userMap
+   * @private
    */
   constructor (ds, sm, userMap) {
+    /**
+     * @type {DeleteSet}
+     * @private
+     */
     this.ds = new DeleteSet()
+    /**
+     * State Map
+     * @type {Map<number,number>}
+     * @private
+     */
     this.sm = sm
+    /**
+     * @type {Map<number,string>}
+     * @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)

src/utils/StructStore.js

@@ -13,6 +13,7 @@ export class StructStore {
   constructor () {
     /**
      * @type {Map<number,Array<AbstractStruct>>}
+     * @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<number,{i:number,refs:Array<AbstractStructRef>}>}
+     * @private
      */
     this.pendingClientsStructRefs = new Map()
     /**
      * Stack of pending structs waiting for struct dependencies
      * Maximum length of stack is structReaders.size
      * @type {Array<AbstractStructRef>}
+     * @private
      */
     this.pendingStack = []
     /**
      * @type {Array<decoding.Decoder>}
+     * @private
      */
     this.pendingDeleteReaders = []
   }
@@ -43,6 +47,9 @@ export class StructStore {
  *
  * @param {StructStore} store
  * @return {Map<number,number>}
+ *
+ * @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<any>} 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<number,number>}
+ *
+ * @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)

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<ID>}
+     * @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

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

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<string, AbstractType<YEvent>>}
@@ -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<any>} 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<T>}
+   *
+   * @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<any>}
+   *
+   * @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])

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<any>} parent
  * @param {AbstractType<any>} child target
  * @return {Array<string|number>} Path to the target
+ *
+ * @private
+ * @function
  */
 const getPathTo = (parent, child) => {
   const path = []

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<number, number>} StateMap
+ * @private
  */
-
 export const structRefs = [
   GCRef,
   ItemBinaryRef,
@@ -45,6 +48,8 @@ export const structRefs = [
  * @param {Array<AbstractStruct>} 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<AbstractStructRef>}
+ *
+ * @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<number,number>} _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<number,Array<AbstractStructRef>>}
+ *
+ * @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<number,{refs:Array<AbstractStructRef>,i:number}>} pendingClientsStructRefs
- * @param {number} client
- * @param {Array<AbstractStructRef>} 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<number, Array<AbstractStructRef>>} 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<number,number>} [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)

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<any>} child
  * @return {Boolean} Whether `parent` is a parent of `child`.
  *
- * @public
+ * @private
+ * @function
  */
 export const isParentOf = (parent, child) => {
   while (child._item !== null) {

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<any>} type
  * @param {number} offset
+ *
+ * @function
  */
 export const createAbsolutePosition = (type, offset) => new AbsolutePosition(type, offset)
 
 /**
  * @param {AbstractType<any>} 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<any>} 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 && (