yonote/yjs
14
0
Fork 0
Code Pull Requests 1 Releases Activity

improve jsdoc comments

Browse Source
This commit is contained in:
Kevin Jahns
2019-04-11 13:18:35 +02:00
parent ed3b31e58f
commit 31ff7ac78c
32 changed files with 477 additions and 114 deletions
Download Patch File Download Diff File Expand all files Collapse all files

61
src/types/AbstractType.js
View File

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

15
src/types/YArray.js
View File

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

19
src/types/YMap.js
View File

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

53
src/types/YText.js
View File

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

12
src/types/YXmlElement.js
View File

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

11
src/types/YXmlEvent.js
View File

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

9
src/types/YXmlHook.js
View File

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

8
src/types/YXmlText.js
View File

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