@ckeditor/ckeditor5-engine 35.4.0 → 36.0.0

package/src/model/markercollection.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */
 /**
@@ -23,16 +23,10 @@ import { CKEditorError, EmitterMixin } from '@ckeditor/ckeditor5-utils';
  * @see module:engine/model/markercollection~Marker
  */
 export default class MarkerCollection extends EmitterMixin() {
-    /**
-     * Creates a markers collection.
-     */
     constructor() {
-        super();
+        super(...arguments);
         /**
          * Stores {@link ~Marker markers} added to the collection.
-         *
-         * @private
-         * @member {Map} #_markers
          */
         this._markers = new Map();
     }
@@ -40,8 +34,6 @@ export default class MarkerCollection extends EmitterMixin() {
      * Iterable interface.
      *
      * Iterates over all {@link ~Marker markers} added to the collection.
-     *
-     * @returns {Iterator}
      */
     [Symbol.iterator]() {
         return this._markers.values();
@@ -49,8 +41,8 @@ export default class MarkerCollection extends EmitterMixin() {
     /**
      * Checks if given {@link ~Marker marker} or marker name is in the collection.
      *
-     * @param {String|module:engine/model/markercollection~Marker} markerOrName Name of marker or marker instance to check.
-     * @returns {Boolean} `true` if marker is in the collection, `false` otherwise.
+     * @param markerOrName Name of marker or marker instance to check.
+     * @returns `true` if marker is in the collection, `false` otherwise.
      */
     has(markerOrName) {
         const markerName = markerOrName instanceof Marker ? markerOrName.name : markerOrName;
@@ -59,8 +51,8 @@ export default class MarkerCollection extends EmitterMixin() {
     /**
      * Returns {@link ~Marker marker} with given `markerName`.
      *
-     * @param {String} markerName Name of marker to get.
-     * @returns {module:engine/model/markercollection~Marker|null} Marker with given name or `null` if such marker was
+     * @param markerName Name of marker to get.
+     * @returns Marker with given name or `null` if such marker was
      * not added to the collection.
      */
     get(markerName) {
@@ -76,14 +68,13 @@ export default class MarkerCollection extends EmitterMixin() {
      * flag has changed.
      *
      * @internal
-     * @protected
-     * @fires module:engine/model/markercollection~MarkerCollection#event:update
-     * @param {String|module:engine/model/markercollection~Marker} markerOrName Name of marker to set or marker instance to update.
-     * @param {module:engine/model/range~Range} range Marker range.
-     * @param {Boolean} [managedUsingOperations=false] Specifies whether the marker is managed using operations.
-     * @param {Boolean} [affectsData=false] Specifies whether the marker affects the data produced by the data pipeline
+     * @fires update
+     * @param markerOrName Name of marker to set or marker instance to update.
+     * @param range Marker range.
+     * @param managedUsingOperations Specifies whether the marker is managed using operations.
+     * @param affectsData Specifies whether the marker affects the data produced by the data pipeline
      * (is persisted in the editor's data).
-     * @returns {module:engine/model/markercollection~Marker} `Marker` instance which was added or updated.
+     * @returns `Marker` instance which was added or updated.
      */
     _set(markerOrName, range, managedUsingOperations = false, affectsData = false) {
         const markerName = markerOrName instanceof Marker ? markerOrName.name : markerOrName;
@@ -127,10 +118,9 @@ export default class MarkerCollection extends EmitterMixin() {
      * Removes given {@link ~Marker marker} or a marker with given name from the `MarkerCollection`.
      *
      * @internal
-     * @protected
-     * @fires module:engine/model/markercollection~MarkerCollection#event:update
-     * @param {String|module:engine/model/markercollection~Marker} markerOrName Marker or name of a marker to remove.
-     * @returns {Boolean} `true` if marker was found and removed, `false` otherwise.
+     * @fires update
+     * @param markerOrName Marker or name of a marker to remove.
+     * @returns `true` if marker was found and removed, `false` otherwise.
      */
     _remove(markerOrName) {
         const markerName = markerOrName instanceof Marker ? markerOrName.name : markerOrName;
@@ -149,9 +139,8 @@ export default class MarkerCollection extends EmitterMixin() {
      * conversion} for the marker.
      *
      * @internal
-     * @protected
-     * @fires module:engine/model/markercollection~MarkerCollection#event:update
-     * @param {String|module:engine/model/markercollection~Marker} markerOrName Marker or name of a marker to refresh.
+     * @fires update
+     * @param markerOrName Marker or name of a marker to refresh.
      */
     _refresh(markerOrName) {
         const markerName = markerOrName instanceof Marker ? markerOrName.name : markerOrName;
@@ -169,9 +158,6 @@ export default class MarkerCollection extends EmitterMixin() {
     }
     /**
      * Returns iterator that iterates over all markers, which ranges contain given {@link module:engine/model/position~Position position}.
-     *
-     * @param {module:engine/model/position~Position} position
-     * @returns {Iterable.<module:engine/model/markercollection~Marker>}
      */
     *getMarkersAtPosition(position) {
         for (const marker of this) {
@@ -182,9 +168,6 @@ export default class MarkerCollection extends EmitterMixin() {
     }
     /**
      * Returns iterator that iterates over all markers, which intersects with given {@link module:engine/model/range~Range range}.
-     *
-     * @param {module:engine/model/range~Range} range
-     * @returns {Iterable.<module:engine/model/markercollection~Marker>}
      */
     *getMarkersIntersectingRange(range) {
         for (const marker of this) {
@@ -206,15 +189,14 @@ export default class MarkerCollection extends EmitterMixin() {
     /**
      * Iterates over all markers that starts with given `prefix`.
      *
-     *		const markerFooA = markersCollection.set( 'foo:a', rangeFooA );
-     *		const markerFooB = markersCollection.set( 'foo:b', rangeFooB );
-     *		const markerBarA = markersCollection.set( 'bar:a', rangeBarA );
-     *		const markerFooBarA = markersCollection.set( 'foobar:a', rangeFooBarA );
-     *		Array.from( markersCollection.getMarkersGroup( 'foo' ) ); // [ markerFooA, markerFooB ]
-     *		Array.from( markersCollection.getMarkersGroup( 'a' ) ); // []
-     *
-     * @param prefix
-     * @returns {Iterable.<module:engine/model/markercollection~Marker>}
+     * ```ts
+     * const markerFooA = markersCollection.set( 'foo:a', rangeFooA );
+     * const markerFooB = markersCollection.set( 'foo:b', rangeFooB );
+     * const markerBarA = markersCollection.set( 'bar:a', rangeBarA );
+     * const markerFooBarA = markersCollection.set( 'foobar:a', rangeFooBarA );
+     * Array.from( markersCollection.getMarkersGroup( 'foo' ) ); // [ markerFooA, markerFooB ]
+     * Array.from( markersCollection.getMarkersGroup( 'a' ) ); // []
+     * ```
      */
     *getMarkersGroup(prefix) {
         for (const marker of this._markers.values()) {
@@ -225,9 +207,6 @@ export default class MarkerCollection extends EmitterMixin() {
     }
     /**
      * Destroys the marker.
-     *
-     * @private
-     * @param {module:engine/model/markercollection~Marker} marker Marker to destroy.
      */
     _destroyMarker(marker) {
         marker.stopListening();
@@ -277,13 +256,15 @@ export default class MarkerCollection extends EmitterMixin() {
  * Both type of them should be added / updated by {@link module:engine/model/writer~Writer#addMarker}
  * and removed by {@link module:engine/model/writer~Writer#removeMarker} methods.
  *
- *		model.change( ( writer ) => {
- * 			const marker = writer.addMarker( name, { range, usingOperation: true } );
+ * ```ts
+ * model.change( ( writer ) => {
+ * 	const marker = writer.addMarker( name, { range, usingOperation: true } );
  *
- * 			// ...
+ * 	// ...
  *
- * 			writer.removeMarker( marker );
- *		} );
+ * 	writer.removeMarker( marker );
+ * } );
+ * ```
  *
  * See {@link module:engine/model/writer~Writer} to find more examples.
  *
@@ -305,50 +286,22 @@ class Marker extends EmitterMixin(TypeCheckable) {
     /**
      * Creates a marker instance.
      *
-     * @param {String} name Marker name.
-     * @param {module:engine/model/liverange~LiveRange} liveRange Range marked by the marker.
-     * @param {Boolean} managedUsingOperations Specifies whether the marker is managed using operations.
-     * @param {Boolean} affectsData Specifies whether the marker affects the data produced by the data pipeline
-     * (is persisted in the editor's data).
+     * @param name Marker name.
+     * @param liveRange Range marked by the marker.
+     * @param managedUsingOperations Specifies whether the marker is managed using operations.
+     * @param affectsData Specifies whether the marker affects the data produced by the data pipeline (is persisted in the editor's data).
      */
     constructor(name, liveRange, managedUsingOperations, affectsData) {
         super();
-        /**
-         * Marker's name.
-         *
-         * @readonly
-         * @type {String}
-         */
         this.name = name;
-        /**
-         * Range marked by the marker.
-         *
-         * @protected
-         * @member {module:engine/model/liverange~LiveRange}
-         */
         this._liveRange = this._attachLiveRange(liveRange);
-        /**
-         * Flag indicates if the marker is managed using operations or not.
-         *
-         * @private
-         * @member {Boolean}
-         */
         this._managedUsingOperations = managedUsingOperations;
-        /**
-         * Specifies whether the marker affects the data produced by the data pipeline
-         * (is persisted in the editor's data).
-         *
-         * @private
-         * @member {Boolean}
-         */
         this._affectsData = affectsData;
     }
     /**
      * A value indicating if the marker is managed using operations.
      * See {@link ~Marker marker class description} to learn more about marker types.
      * See {@link module:engine/model/writer~Writer#addMarker}.
-     *
-     * @returns {Boolean}
      */
     get managedUsingOperations() {
         if (!this._liveRange) {
@@ -358,8 +311,6 @@ class Marker extends EmitterMixin(TypeCheckable) {
     }
     /**
      * A value indicating if the marker changes the data.
-     *
-     * @returns {Boolean}
      */
     get affectsData() {
         if (!this._liveRange) {
@@ -369,8 +320,6 @@ class Marker extends EmitterMixin(TypeCheckable) {
     }
     /**
      * Returns the marker data (properties defining the marker).
-     *
-     * @returns {module:engine/model/markercollection~MarkerData}
      */
     getData() {
         return {
@@ -381,8 +330,6 @@ class Marker extends EmitterMixin(TypeCheckable) {
     }
     /**
      * Returns current marker start position.
-     *
-     * @returns {module:engine/model/position~Position}
      */
     getStart() {
         if (!this._liveRange) {
@@ -392,8 +339,6 @@ class Marker extends EmitterMixin(TypeCheckable) {
     }
     /**
      * Returns current marker end position.
-     *
-     * @returns {module:engine/model/position~Position}
      */
     getEnd() {
         if (!this._liveRange) {
@@ -410,8 +355,6 @@ class Marker extends EmitterMixin(TypeCheckable) {
      * and get `Marker` instance from {@link module:engine/model/markercollection~MarkerCollection MarkerCollection} every
      * time there is a need to read marker properties. This will guarantee that the marker has not been removed and
      * that it's data is up-to-date.
-     *
-     * @returns {module:engine/model/range~Range}
      */
     getRange() {
         if (!this._liveRange) {
@@ -423,9 +366,8 @@ class Marker extends EmitterMixin(TypeCheckable) {
      * Binds new live range to the marker and detach the old one if is attached.
      *
      * @internal
-     * @protected
-     * @param {module:engine/model/liverange~LiveRange} liveRange Live range to attach
-     * @returns {module:engine/model/liverange~LiveRange} Attached live range.
+     * @param liveRange Live range to attach
+     * @returns Attached live range.
      */
     _attachLiveRange(liveRange) {
         if (this._liveRange) {
@@ -441,7 +383,6 @@ class Marker extends EmitterMixin(TypeCheckable) {
      * Unbinds and destroys currently attached live range.
      *
      * @internal
-     * @protected
      */
     _detachLiveRange() {
         this._liveRange.stopDelegating('change:range', this);
@@ -450,20 +391,8 @@ class Marker extends EmitterMixin(TypeCheckable) {
         this._liveRange = null;
     }
 }
-/**
- * Checks whether this object is of the given.
- *
- *		marker.is( 'marker' ); // -> true
- *		marker.is( 'model:marker' ); // -> true
- *
- *		marker.is( 'view:element' ); // -> false
- *		marker.is( 'documentSelection' ); // -> false
- *
- * {@link module:engine/model/node~Node#is Check the entire list of model objects} which implement the `is()` method.
- *
- * @param {String} type
- * @returns {Boolean}
- */
+// The magic of type inference using `is` method is centralized in `TypeCheckable` class.
+// Proper overload would interfere with that.
 Marker.prototype.is = function (type) {
     return type === 'marker' || type === 'model:marker';
 };