Browse Source

Update DowncastDispatcher#_mapChangesWithAutomaticReconversion() docs.

Maciej Gołaszewski 5 years ago
parent
commit
d193903b0c
1 changed files with 23 additions and 2 deletions
  1. 23 2
      packages/ckeditor5-engine/src/conversion/downcastdispatcher.js

+ 23 - 2
packages/ckeditor5-engine/src/conversion/downcastdispatcher.js

@@ -591,11 +591,32 @@ export default class DowncastDispatcher {
 	}
 
 	/**
-	 * Get changes without those that needs to be converted using {@link #reconvertElement} defined by a `triggerBy` configuration for
+	 * Returns differ changes together with added "reconvert" type changes for {@link #reconvertElement}. Those are defined by
+	 * a `triggerBy` configuration for
 	 * {@link module:engine/conversion/downcasthelpers~DowncastHelpers#elementToElement `elementToElement()`} conversion helper.
 	 *
+	 * This method will remove every mapped insert or remove change with a single "reconvert" changes.
+	 *
+	 * For instance: Having a `triggerBy` configuration defined for `<complex>` element that issues this element reconversion on
+	 * `foo` and `bar` attributes change, and a set of changes for this element:
+	 *
+	 *		const differChanges = [
+	 *			{ type: 'attribute', attributeKey: 'foo', ... },
+	 *			{ type: 'attribute', attributeKey: 'bar', ... },
+	 *			{ type: 'attribute', attributeKey: 'baz', ... }
+	 *		];
+	 *
+	 * This method will return:
+	 *
+	 *		const updatedChanges = [
+	 *			{ type: 'reconvert', element: complexElementInstance },
+	 *			{ type: 'attribute', attributeKey: 'baz', ... }
+	 *		];
+	 *
+	 * In the example above the `'baz'` attribute change will fire an {@link #event:attribute attribute event}
+	 *
 	 * @param {module:engine/model/differ~Differ} differ The differ object with buffered changes.
-	 * @returns {Array.<Object>}
+	 * @returns {Array.<Object>} Updated set of changes.
 	 * @private
 	 */
 	_mapChangesWithAutomaticReconversion( differ ) {