cleanup docs

src/Bindings/Binding.js

@@ -2,7 +2,7 @@
 import { createMutualExclude } from '../Util/mutualExclude.js'
 
 /**
- * Abstract class for bindings
+ * Abstract class for bindings.
  *
  * A binding handles data binding from a Yjs type to a data object. For example,
  * you can bind a Quill editor instance to a YText instance with the `QuillBinding` class.
@@ -18,16 +18,27 @@ import { createMutualExclude } from '../Util/mutualExclude.js'
  */
 export default class Binding {
   /**
-   * @param {YType} type Yjs type
-   * @param {any} target Binding Target
+   * @param {YType} type Yjs type.
+   * @param {any} target Binding Target.
    */
   constructor (type, target) {
+    /**
+     * The Yjs type that is bound to `target`
+     * @type {YType}
+     */
     this.type = type
+    /**
+     * The target that `type` is bound to.
+     * @type {*}
+     */
     this.target = target
+    /**
+     * @private
+     */
     this._mutualExclude = createMutualExclude()
   }
   /**
-   * Remove all data observers (both from the type and th target).
+   * Remove all data observers (both from the type and the target).
    */
   destroy () {
     this.type = null

src/Bindings/DomBinding/DomBinding.js

@@ -17,9 +17,9 @@ import { removeAssociation } from './util.js'
  * This binding is automatically destroyed when its parent is deleted.
  *
  * @example
- *   const div = document.createElement('div')
- *   const type = y.define('xml', Y.XmlFragment)
- *   const binding = new Y.QuillBinding(type, div)
+ * const div = document.createElement('div')
+ * const type = y.define('xml', Y.XmlFragment)
+ * const binding = new Y.QuillBinding(type, div)
  *
  */
 export default class DomBinding extends Binding {
@@ -27,12 +27,28 @@ export default class DomBinding extends Binding {
    * @param {YXmlFragment} type The bind source. This is the ultimate source of
    *                            truth.
    * @param {Element} target The bind target. Mirrors the target.
+   * @param {Object} [opts] Optional configurations
+
+   * @param {FilterFunction} [opts.filter=defaultFilter] The filter function to use.
    */
   constructor (type, target, opts = {}) {
     // Binding handles textType as this.type and domTextarea as this.target
     super(type, target)
+    /**
+     * Maps each DOM element to the type that it is associated with.
+     * @type {Map}
+     */
     this.domToType = new Map()
+    /**
+     * Maps each YXml type to the DOM element that it is associated with.
+     * @type {Map}
+     */
     this.typeToDom = new Map()
+    /**
+     * Defines which DOM attributes and elements to filter out.
+     * Also filters remote changes.
+     * @type {FilterFunction}
+     */
     this.filter = opts.filter || defaultFilter
     // set initial value
     target.innerHTML = ''
@@ -103,6 +119,7 @@ export default class DomBinding extends Binding {
 
   /**
    * NOTE: currently does not apply filter to existing elements!
+   * @param {FilterFunction} filter The filter function to use from now on.
    */
   setFilter (filter) {
     this.filter = filter
@@ -110,7 +127,7 @@ export default class DomBinding extends Binding {
   }
 
   /**
-   * Remove all properties that are handled by this class
+   * Remove all properties that are handled by this class.
    */
   destroy () {
     this.domToType = null
@@ -125,3 +142,11 @@ export default class DomBinding extends Binding {
     super.destroy()
   }
 }
+
+  /**
+   * A filter defines which elements and attributes to share.
+   * Return null if the node should be filtered. Otherwise return the Map of
+   * accepted attributes.
+   *
+   * @typedef {function(nodeName: String, attrs: Map): Map|null} FilterFunction
+   */

src/Bindings/DomBinding/domObserver.js

@@ -7,7 +7,7 @@ import {
 import diff from '../../Util/simpleDiff.js'
 import YXmlFragment from '../../Types/YXml/YXmlFragment.js'
 
-/*
+/**
  * 1. Check if any of the nodes was deleted
  * 2. Iterate over the children.
  *    2.1 If a node exists that is not yet bound to a type, insert a new node
@@ -17,6 +17,7 @@ import YXmlFragment from '../../Types/YXml/YXmlFragment.js'
  *       recreate a new yxml element that is bound to that node.
  *       You can detect that a node was moved because expectedId
  *       !== actualId in the list
+ * @private
  */
 function applyChangesFromDom (binding, dom, yxml, _document) {
   if (yxml == null || yxml === false || yxml.constructor === YXmlHook) {
@@ -79,6 +80,9 @@ function applyChangesFromDom (binding, dom, yxml, _document) {
   }
 }
 
+/**
+ * @private
+ */
 export default function domObserver (mutations, _document) {
   this._mutualExclude(() => {
     this.type._y.transact(() => {

src/Bindings/DomBinding/domToType.js

@@ -5,7 +5,11 @@ import { createAssociation } from './util.js'
 /**
  * Creates a Yjs type (YXml) based on the contents of a DOM Element.
  *
- * @param {Element|TextNode}
+ * @param {Element|TextNode} element The DOM Element
+ * @param {?Document} _document Optional. Provide the global document object.
+ * @param {?DomBinding} binding This property should only be set if the type
+ *                              is going to be bound with the dom-binding.
+ * @return {YXmlElement | YXmlText}
  */
 export default function domToType (element, _document = document, binding) {
   let type

src/Bindings/DomBinding/filter.js

@@ -1,10 +1,27 @@
 import isParentOf from '../../Util/isParentOf.js'
 
+/**
+ * Default filter method (does nothing).
+ *
+ * @param {String} nodeName The nodeName of the element
+ * @param {Map} attrs Map of key-value pairs that are attributes of the node.
+ * @return {Map | null} The allowed attributes or null, if the element should be
+ *                      filtered.
+ */
 export function defaultFilter (nodeName, attrs) {
+  // TODO: implement basic filter that filters out dangerous properties!
   return attrs
 }
 
-
+/**
+ * Applies a filter on a type.
+ *
+ * @param {Y} y The Yjs instance.
+ * @param {DomBinding} binding The DOM binding instance that has the dom filter.
+ * @param {YXmlElement | YXmlFragment } type The type to apply the filter to.
+ *
+ * @private
+ */
 export function applyFilterOnType (y, binding, type) {
   if (isParentOf(binding.type, type)) {
     const nodeName = type.nodeName

src/Bindings/DomBinding/selection.js

@@ -5,6 +5,9 @@ import { getRelativePosition, fromRelativePosition } from '../../Util/relativePo
 let browserSelection = null
 let relativeSelection = null
 
+/**
+ * @private
+ */
 export let beforeTransactionSelectionFixer
 if (typeof getSelection !== 'undefined') {
   beforeTransactionSelectionFixer = function _beforeTransactionSelectionFixer (y, domBinding, transaction, remote) {
@@ -30,6 +33,9 @@ if (typeof getSelection !== 'undefined') {
   beforeTransactionSelectionFixer = function _fakeBeforeTransactionSelectionFixer () {}
 }
 
+/**
+ * @private
+ */
 export function afterTransactionSelectionFixer (y, domBinding, transaction, remote) {
   if (relativeSelection === null || !remote) {
     return

src/Bindings/DomBinding/typeObserver.js

@@ -3,6 +3,9 @@ import YXmlText from '../../Types/YXml/YXmlText.js'
 import YXmlHook from '../../Types/YXml/YXmlHook.js'
 import { removeDomChildrenUntilElementFound } from './util.js'
 
+/**
+ * @private
+ */
 export default function typeObserver (events, _document) {
   this._mutualExclude(() => {
     events.forEach(event => {

src/Bindings/DomBinding/util.js

@@ -1,6 +1,11 @@
 
 import domToType from './domToType.js'
 
+/**
+ * Iterates items until an undeleted item is found.
+ *
+ * @private
+ */
 export function iterateUntilUndeleted (item) {
   while (item !== null && item._deleted) {
     item = item._right
@@ -8,11 +13,23 @@ export function iterateUntilUndeleted (item) {
   return item
 }
 
+/**
+ * Removes an association (the information that a DOM element belongs to a
+ * type).
+ *
+ * @private
+ */
 export function removeAssociation (domBinding, dom, type) {
   domBinding.domToType.delete(dom)
   domBinding.typeToDom.delete(type)
 }
 
+/**
+ * Creates an association (the information that a DOM element belongs to a
+ * type).
+ *
+ * @private
+ */
 export function createAssociation (domBinding, dom, type) {
   if (domBinding !== undefined) {
     domBinding.domToType.set(dom, type)
@@ -31,12 +48,18 @@ export function createAssociation (domBinding, dom, type) {
  *                           the beginning.
  * @param {Array<Element>} doms The Dom elements to insert.
  * @param {?Document} _document Optional. Provide the global document object.
+ * @param {DomBinding} binding The dom binding
  * @return {Array<YXmlElement>} The YxmlElements that are inserted.
+ *
+ * @private
  */
 export function insertDomElementsAfter (type, prev, doms, _document, binding) {
   return type.insertAfter(prev, doms.map(dom => domToType(dom, _document, binding)))
 }
 
+/**
+ * @private
+ */
 export function insertNodeHelper (yxml, prevExpectedNode, child, _document, binding) {
   let insertedNodes = insertDomElementsAfter(yxml, prevExpectedNode, [child], _document, binding)
   if (insertedNodes.length > 0) {
@@ -54,6 +77,8 @@ export function insertNodeHelper (yxml, prevExpectedNode, child, _document, bind
  * @param {Element} currentChild Start removing elements with `currentChild`. If
  *                               `currentChild` is `elem` it won't be removed.
  * @param {Element|null} elem The elemnt to look for.
+ *
+ * @private
  */
 export function removeDomChildrenUntilElementFound (parent, currentChild, elem) {
   while (currentChild !== elem) {