From 929ee77bf7ad2959fe3ebd50eb0aafa25e5d27b7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Krzysztof=20Krzto=C5=84?= Date: Wed, 28 Nov 2018 18:01:06 +0100 Subject: [PATCH 1/4] Docs: Rewrite of conversion APIs docs. Introduced 'DowncastConversionApi' and renamed 'ViewConversionApi' to 'UpcastConversionApi'. --- src/conversion/downcastdispatcher.js | 57 ++++++++++++++++++++++++---- src/conversion/upcast-converters.js | 2 +- src/conversion/upcastdispatcher.js | 33 ++++++++++------ 3 files changed, 72 insertions(+), 20 deletions(-) diff --git a/src/conversion/downcastdispatcher.js b/src/conversion/downcastdispatcher.js index 217676f05..64203a642 100644 --- a/src/conversion/downcastdispatcher.js +++ b/src/conversion/downcastdispatcher.js @@ -105,13 +105,15 @@ export default class DowncastDispatcher { /** * Creates a `DowncastDispatcher` instance. * - * @param {Object} [conversionApi] Interface passed by dispatcher to the events calls. + * @see module:engine/conversion/downcastdispatcher~DowncastConversionApi + * @param {Object} [conversionApi] Additional properties for interface that will be passed to events fired + * by `DowncastDispatcher`. */ constructor( conversionApi = {} ) { /** * Interface passed by dispatcher to the events callbacks. * - * @member {Object} + * @member {module:engine/conversion/downcastdispatcher~DowncastConversionApi} */ this.conversionApi = extend( { dispatcher: this }, conversionApi ); } @@ -481,7 +483,8 @@ export default class DowncastDispatcher { * @param {Object} data Additional information about the change. * @param {module:engine/model/item~Item} data.item Inserted item. * @param {module:engine/model/range~Range} data.range Range spanning over inserted item. - * @param {Object} conversionApi Conversion interface to be used by callback, passed in `DowncastDispatcher` constructor. + * @param {module:engine/conversion/downcastdispatcher~DowncastConversionApi} conversionApi Conversion interface + * to be used by callback, passed in `DowncastDispatcher` constructor. */ /** @@ -497,7 +500,8 @@ export default class DowncastDispatcher { * @param {Object} data Additional information about the change. * @param {module:engine/model/position~Position} data.position Position from which the node has been removed. * @param {Number} data.length Offset size of the removed node. - * @param {Object} conversionApi Conversion interface to be used by callback, passed in `DowncastDispatcher` constructor. + * @param {module:engine/conversion/downcastdispatcher~DowncastConversionApi} conversionApi Conversion interface + * to be used by callback, passed in `DowncastDispatcher` constructor. */ /** @@ -523,7 +527,8 @@ export default class DowncastDispatcher { * @param {*} data.attributeOldValue Attribute value before the change. This is `null` when selection attribute is converted. * @param {*} data.attributeNewValue New attribute value. * @param {module:engine/conversion/modelconsumable~ModelConsumable} consumable Values to consume. - * @param {Object} conversionApi Conversion interface to be used by callback, passed in `DowncastDispatcher` constructor. + * @param {module:engine/conversion/downcastdispatcher~DowncastConversionApi} conversionApi Conversion interface + * to be used by callback, passed in `DowncastDispatcher` constructor. */ /** @@ -532,7 +537,8 @@ export default class DowncastDispatcher { * @event selection * @param {module:engine/model/selection~Selection} selection Selection that is converted. * @param {module:engine/conversion/modelconsumable~ModelConsumable} consumable Values to consume. - * @param {Object} conversionApi Conversion interface to be used by callback, passed in `DowncastDispatcher` constructor. + * @param {module:engine/conversion/downcastdispatcher~DowncastConversionApi} conversionApi Conversion interface + * to be used by callback, passed in `DowncastDispatcher` constructor. */ /** @@ -567,7 +573,8 @@ export default class DowncastDispatcher { * @param {module:engine/model/range~Range} data.markerRange Marker range. * @param {String} data.markerName Marker name. * @param {module:engine/conversion/modelconsumable~ModelConsumable} consumable Values to consume. - * @param {Object} conversionApi Conversion interface to be used by callback, passed in `DowncastDispatcher` constructor. + * @param {module:engine/conversion/downcastdispatcher~DowncastConversionApi} conversionApi Conversion interface + * to be used by callback, passed in `DowncastDispatcher` constructor. */ /** @@ -582,7 +589,8 @@ export default class DowncastDispatcher { * @param {Object} data Additional information about the change. * @param {module:engine/model/range~Range} data.markerRange Marker range. * @param {String} data.markerName Marker name. - * @param {Object} conversionApi Conversion interface to be used by callback, passed in `DowncastDispatcher` constructor. + * @param {module:engine/conversion/downcastdispatcher~DowncastConversionApi} conversionApi Conversion interface + * to be used by callback, passed in `DowncastDispatcher` constructor. */ } @@ -611,3 +619,36 @@ function shouldMarkerChangeBeConverted( modelPosition, marker, mapper ) { return !hasCustomHandling; } + +/** + * Conversion interface that is registered for given {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher} + * and is passed as one of parameters when {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher dispatcher} + * fires it's events. + * + * @interface DowncastConversionApi + */ + +/** + * The {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher} instance. + * + * @member {module:engine/conversion/downcastdispatcher~DowncastDispatcher} #dispatcher + */ + +/** + * Stores information about what parts of processed model item are still waiting to be handled. After a piece of model item + * was converted, appropriate consumable value should be {@link module:engine/conversion/modelconsumable~ModelConsumable#consume consumed}. + * + * @member {module:engine/conversion/modelconsumable~ModelConsumable} #consumable + */ + +/** + * The {@link module:engine/conversion/mapper~Mapper} instance. + * + * @member {module:engine/conversion/mapper~Mapper} #mapper + */ + +/** + * The {@link module:engine/view/downcastwriter~DowncastWriter} instance used to manipulate data during conversion. + * + * @member {module:engine/view/downcastwriter~DowncastWriter} #writer + */ diff --git a/src/conversion/upcast-converters.js b/src/conversion/upcast-converters.js index 2caabdb10..8ddd300bb 100644 --- a/src/conversion/upcast-converters.js +++ b/src/conversion/upcast-converters.js @@ -528,7 +528,7 @@ function _onlyViewNameIsDefined( config ) { // // @param {module:engine/model/range~Range} modelRange Model range on which attribute should be set. // @param {Object} modelAttribute Model attribute to set. -// @param {Object} conversionApi Conversion API. +// @param {module:engine/conversion/upcastdispatcher~UpcastConversionApi} conversionApi Conversion API. // @param {Boolean} shallow If set to `true` the attribute will be set only on top-level nodes. Otherwise, it will be set // on all elements in the range. // @returns {Boolean} `true` if attribute was set on at least one node from given `modelRange`. diff --git a/src/conversion/upcastdispatcher.js b/src/conversion/upcastdispatcher.js index 39c49656e..48d8fbed9 100644 --- a/src/conversion/upcastdispatcher.js +++ b/src/conversion/upcastdispatcher.js @@ -102,7 +102,7 @@ export default class UpcastDispatcher { /** * Creates a `UpcastDispatcher` that operates using passed API. * - * @see module:engine/conversion/upcastdispatcher~ViewConversionApi + * @see module:engine/conversion/upcastdispatcher~UpcastConversionApi * @param {Object} [conversionApi] Additional properties for interface that will be passed to events fired * by `UpcastDispatcher`. */ @@ -131,7 +131,7 @@ export default class UpcastDispatcher { /** * Interface passed by dispatcher to the events callbacks. * - * @member {module:engine/conversion/upcastdispatcher~ViewConversionApi} + * @member {module:engine/conversion/upcastdispatcher~UpcastConversionApi} */ this.conversionApi = Object.assign( {}, conversionApi ); @@ -209,7 +209,7 @@ export default class UpcastDispatcher { /** * @private - * @see module:engine/conversion/upcastdispatcher~ViewConversionApi#convertItem + * @see module:engine/conversion/upcastdispatcher~UpcastConversionApi#convertItem */ _convertItem( viewItem, modelCursor ) { const data = Object.assign( { viewItem, modelCursor, modelRange: null } ); @@ -239,7 +239,7 @@ export default class UpcastDispatcher { /** * @private - * @see module:engine/conversion/upcastdispatcher~ViewConversionApi#convertChildren + * @see module:engine/conversion/upcastdispatcher~UpcastConversionApi#convertChildren */ _convertChildren( viewItem, modelCursor ) { const modelRange = new ModelRange( modelCursor ); @@ -259,7 +259,7 @@ export default class UpcastDispatcher { /** * @private - * @see module:engine/conversion/upcastdispatcher~ViewConversionApi#splitToAllowedParent + * @see module:engine/conversion/upcastdispatcher~UpcastConversionApi#splitToAllowedParent */ _splitToAllowedParent( node, modelCursor ) { // Try to find allowed parent. @@ -348,7 +348,7 @@ export default class UpcastDispatcher { * Change this value for the next converter to tell where the conversion should continue. * @param {module:engine/model/range~Range} data.modelRange The current state of conversion result. Every change to * converted element should be reflected by setting or modifying this property. - * @param {ViewConversionApi} conversionApi Conversion utilities to be used by callback. + * @param {module:engine/model/upcastdispatcher~UpcastConversionApi} conversionApi Conversion utilities to be used by callback. */ /** @@ -436,7 +436,7 @@ function createContextTree( contextDefinition, writer ) { * and is passed as one of parameters when {@link module:engine/conversion/upcastdispatcher~UpcastDispatcher dispatcher} * fires it's events. * - * @interface ViewConversionApi + * @interface UpcastConversionApi */ /** @@ -505,11 +505,10 @@ function createContextTree( contextDefinition, writer ) { */ /** - * Instance of {@link module:engine/conversion/viewconsumable~ViewConsumable}. It stores - * information about what parts of processed view item are still waiting to be handled. After a piece of view item + * Stores information about what parts of processed view item are still waiting to be handled. After a piece of view item * was converted, appropriate consumable value should be {@link module:engine/conversion/viewconsumable~ViewConsumable#consume consumed}. * - * @param {Object} #consumable + * @member {module:engine/conversion/viewconsumable~ViewConsumable} #consumable */ /** @@ -520,5 +519,17 @@ function createContextTree( contextDefinition, writer ) { * {@link module:engine/conversion/upcastdispatcher~UpcastDispatcher#event:element} is that `data` parameters allows you * to pass parameters within a single event and `store` within the whole conversion. * - * @param {Object} #store + * @member {Object} #store + */ + +/** + * The model's schema instance. + * + * @member {module:engine/model/schema~Schema} #schema + */ + +/** + * The {@link module:engine/model/writer~Writer} instance used to manipulate data during conversion. + * + * @member {module:engine/model/writer~Writer} #writer */ From 95373b314c1bc1f44848a6645be633cfb09dc7a5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Maciej=20Go=C5=82aszewski?= Date: Fri, 4 Jan 2019 10:28:10 +0100 Subject: [PATCH 2/4] Update links to DowncastConversionApi. --- src/conversion/downcasthelpers.js | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/conversion/downcasthelpers.js b/src/conversion/downcasthelpers.js index 51215ef00..e96dc79b5 100644 --- a/src/conversion/downcasthelpers.js +++ b/src/conversion/downcasthelpers.js @@ -263,7 +263,8 @@ export default class DowncastHelpers extends ConversionHelpers { * * If a function is passed as the `config.view` parameter, it will be used to generate both boundary elements. The function * receives the `data` object as a parameter and should return an instance of the - * {@link module:engine/view/uielement~UIElement view UI element}. The `data` and `conversionApi` objects are passed from + * {@link module:engine/view/uielement~UIElement view UI element}. The `data` object and + * {@link module:engine/conversion/downcastdispatcher~DowncastConversionApi `conversionApi`} are passed from * {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:addMarker}. Additionally, * the `data.isOpening` parameter is passed, which is set to `true` for the marker start boundary element, and `false` to * the marker end boundary element. From e37a8a2b0eb32f3e349b59f2b20031aea889e709 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Maciej=20Go=C5=82aszewski?= Date: Fri, 4 Jan 2019 10:28:23 +0100 Subject: [PATCH 3/4] Update links to UpcastConversionApi. --- src/conversion/upcastdispatcher.js | 2 +- src/conversion/upcasthelpers.js | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/conversion/upcastdispatcher.js b/src/conversion/upcastdispatcher.js index 48d8fbed9..5933637d0 100644 --- a/src/conversion/upcastdispatcher.js +++ b/src/conversion/upcastdispatcher.js @@ -348,7 +348,7 @@ export default class UpcastDispatcher { * Change this value for the next converter to tell where the conversion should continue. * @param {module:engine/model/range~Range} data.modelRange The current state of conversion result. Every change to * converted element should be reflected by setting or modifying this property. - * @param {module:engine/model/upcastdispatcher~UpcastConversionApi} conversionApi Conversion utilities to be used by callback. + * @param {module:engine/conversion/upcastdispatcher~UpcastConversionApi} conversionApi Conversion utilities to be used by callback. */ /** diff --git a/src/conversion/upcasthelpers.js b/src/conversion/upcasthelpers.js index 34657753e..71282af2b 100644 --- a/src/conversion/upcasthelpers.js +++ b/src/conversion/upcasthelpers.js @@ -722,7 +722,7 @@ function onlyViewNameIsDefined( config ) { // // @param {module:engine/model/range~Range} modelRange Model range on which attribute should be set. // @param {Object} modelAttribute Model attribute to set. -// @param {Object} conversionApi Conversion API. +// @param {module:engine/conversion/upcastdispatcher~UpcastConversionApi} conversionApi Conversion API. // @param {Boolean} shallow If set to `true` the attribute will be set only on top-level nodes. Otherwise, it will be set // on all elements in the range. // @returns {Boolean} `true` if attribute was set on at least one node from given `modelRange`. From d8723e12958ce900c90eb356946c57424f054b81 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Maciej=20Go=C5=82aszewski?= Date: Fri, 4 Jan 2019 10:42:12 +0100 Subject: [PATCH 4/4] Add full module path to *castConversionApi @interface definition. --- src/conversion/downcastdispatcher.js | 2 +- src/conversion/upcastdispatcher.js | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/conversion/downcastdispatcher.js b/src/conversion/downcastdispatcher.js index 0be27cb78..eeb273b8b 100644 --- a/src/conversion/downcastdispatcher.js +++ b/src/conversion/downcastdispatcher.js @@ -631,7 +631,7 @@ function shouldMarkerChangeBeConverted( modelPosition, marker, mapper ) { * and is passed as one of parameters when {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher dispatcher} * fires it's events. * - * @interface DowncastConversionApi + * @interface module:engine/conversion/downcastdispatcher~DowncastConversionApi */ /** diff --git a/src/conversion/upcastdispatcher.js b/src/conversion/upcastdispatcher.js index 5933637d0..b3de61897 100644 --- a/src/conversion/upcastdispatcher.js +++ b/src/conversion/upcastdispatcher.js @@ -436,7 +436,7 @@ function createContextTree( contextDefinition, writer ) { * and is passed as one of parameters when {@link module:engine/conversion/upcastdispatcher~UpcastDispatcher dispatcher} * fires it's events. * - * @interface UpcastConversionApi + * @interface module:engine/conversion/upcastdispatcher~UpcastConversionApi */ /**