diff --git a/packages/ckeditor5-engine/src/conversion/downcastdispatcher.js b/packages/ckeditor5-engine/src/conversion/downcastdispatcher.js index d021a18e3e6..4f0b30c127a 100644 --- a/packages/ckeditor5-engine/src/conversion/downcastdispatcher.js +++ b/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 `` 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.} + * @returns {Array.} Updated set of changes. * @private */ _mapChangesWithAutomaticReconversion( differ ) {