big documentation update - all public functions and classes are documented now

src/Struct/Item.js

@@ -5,11 +5,12 @@ import Delete from './Delete.js'
 import { transactionTypeChanged } from '../Transaction.js'
 
 /**
- * Helper utility to split an Item (see _splitAt)
- * - copy all properties from a to b
- * - connect a to b
+ * @private
+ * Helper utility to split an Item (see {@link Item#_splitAt})
+ * - copies all properties from a to b
+ * - connects a to b
  * - assigns the correct _id
- * - save b to os
+ * - saves b to os
  */
 export function splitHelper (y, a, b, diff) {
   const aID = a._id
@@ -46,6 +47,10 @@ export function splitHelper (y, a, b, diff) {
   }
 }
 
+/**
+ * @private
+ * Abstract class that represents any content.
+ */
 export default class Item {
   constructor () {
     this._id = null
@@ -58,14 +63,18 @@ export default class Item {
     this._deleted = false
     this._redone = null
   }
+
   /**
-   * Create a operation with the same effect (without position effect)
+   * @private
+   * Creates an Item with the same effect as this Item (without position effect)
    */
   _copy () {
     return new this.constructor()
   }
+
   /**
-   * Redo the effect of this operation.
+   * @private
+   * Redoes the effect of this operation.
    */
   _redo (y) {
     if (this._redone !== null) {
@@ -106,27 +115,43 @@ export default class Item {
     return struct
   }
 
+  /**
+   * @private
+   * Computes the last content address of this Item.
+   */
   get _lastId () {
     return new ID(this._id.user, this._id.clock + this._length - 1)
   }
+
+  /**
+   * @private
+   * Computes the length of this Item.
+   */
   get _length () {
     return 1
   }
+
   /**
-   * Some elements are not supposed to be addressable. For example, an
-   * ItemFormat should not be retrievable via yarray.get(pos)
+   * @private
+   * Should return false if this Item is some kind of meta information
+   * (e.g. format information).
+   *
+   * * Whether this Item should be addressable via `yarray.get(i)`
+   * * Whether this Item should be counted when computing yarray.length
    */
   get _countable () {
     return true
   }
+
   /**
-   * Splits this struct so that another struct can be inserted in-between.
+   * @private
+   * Splits this Item so that another Items can be inserted in-between.
    * This must be overwritten if _length > 1
    * Returns right part after split
-   * - diff === 0 => this
-   * - diff === length => this._right
-   * - otherwise => split _content and return right part of split
-   * (see ItemJSON/ItemString for implementation)
+   * * diff === 0 => this
+   * * diff === length => this._right
+   * * otherwise => split _content and return right part of split
+   * (see {@link ItemJSON}/{@link ItemString} for implementation)
    */
   _splitAt (y, diff) {
     if (diff === 0) {
@@ -134,6 +159,15 @@ export default class Item {
     }
     return this._right
   }
+
+  /**
+   * @private
+   * Mark this Item as deleted.
+   *
+   * @param {Y} y The Yjs instance
+   * @param {boolean} createDelete Whether to propagate a message that this
+   *                               Type was deleted.
+   */
   _delete (y, createDelete = true) {
     if (!this._deleted) {
       this._deleted = true
@@ -152,17 +186,27 @@ export default class Item {
       y._transaction.deletedStructs.add(this)
     }
   }
+
   /**
-   * This is called right before this struct receives any children.
+   * @private
+   * This is called right before this Item receives any children.
    * It can be overwritten to apply pending changes before applying remote changes
    */
   _beforeChange () {
     // nop
   }
-  /*
-   * - Integrate the struct so that other types/structs can see it
-   * - Add this struct to y.os
-   * - Check if this is struct deleted
+
+  /**
+   * @private
+   * Integrates this Item into the shared structure.
+   *
+   * This method actually applies the change to the Yjs instance. In case of
+   * Item it connects _left and _right to this Item and calls the
+   * {@link Item#beforeChange} method.
+   *
+   * * Integrate the struct so that other types/structs can see it
+   * * Add this struct to y.os
+   * * Check if this is struct deleted
    */
   _integrate (y) {
     y._transaction.newTypes.add(this)
@@ -188,6 +232,7 @@ export default class Item {
       // or this types is new
       this._parent._beforeChange()
     }
+
     /*
     # $this has to find a unique position between origin and the next known character
     # case 1: $origin equals $o.origin: the $creator parameter decides if left or right
@@ -280,6 +325,16 @@ export default class Item {
       }
     }
   }
+
+  /**
+   * @private
+   * Transform the properties of this type to binary and write it to an
+   * BinaryEncoder.
+   *
+   * This is called when this Item is sent to a remote peer.
+   *
+   * @param {BinaryEncoder} encoder The encoder to write data to.
+   */
   _toBinary (encoder) {
     encoder.writeUint8(getReference(this.constructor))
     let info = 0
@@ -320,6 +375,16 @@ export default class Item {
       encoder.writeVarString(JSON.stringify(this._parentSub))
     }
   }
+
+  /**
+   * @private
+   * Read the next Item in a Decoder and fill this Item with the read data.
+   *
+   * This is called when data is received from a remote peer.
+   *
+   * @param {Y} y The Yjs instance that this Item belongs to.
+   * @param {BinaryDecoder} decoder The decoder object to read data from.
+   */
   _fromBinary (y, decoder) {
     let missing = []
     const info = decoder.readUint8()