improve jsdoc comments

2019-04-11 13:18:35 +02:00
parent ed3b31e58f
commit 31ff7ac78c
32 changed files with 477 additions and 114 deletions
--- 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<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()
--- 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<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)
--- 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<any>} type
 * @return {string}
+ *
+ * @private
+ * @function
 */
 export const findRootTypeKey = type => {
  // @ts-ignore _y must be defined, otherwise unexpected case
--- a/src/utils/Snapshot.js
+++ b/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)
--- a/src/utils/StructStore.js
+++ b/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)
--- 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<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
--- 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
--- 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<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])
--- 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<any>} parent
 * @param {AbstractType<any>} child target
 * @return {Array<string|number>} Path to the target
+ *
+ * @private
+ * @function
 */
 const getPathTo = (parent, child) => {
  const path = []
--- a/src/utils/structEncoding.js
+++ b/src/utils/structEncoding.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)
--- 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<any>} child
 * @return {Boolean} Whether `parent` is a parent of `child`.
 *
- * @public
+ * @private
+ * @function
 */
 export const isParentOf = (parent, child) => {
  while (child._item !== null) {
--- 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<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 && (