8
0
Просмотр исходного кода

Update conversion utility helpers documentation.

Maciej Gołaszewski 7 лет назад
Родитель
Сommit
2af5bf8fda

+ 17 - 16
packages/ckeditor5-engine/src/conversion/conversion.js

@@ -97,13 +97,16 @@ export default class Conversion {
 		this._dispatchersGroups.set( options.name, group );
 	}
 
+	/* eslint-disable max-len */
 	/**
 	 * Provides chainable API to assign converters to dispatchers registered under a given group name. Converters are added
-	 * by calling the `.add()` method of an object returned by this function.
+	 * by calling the {@link module:engine/conversion/conversion~ConversionHelpers#add `.add()`} method of an
+	 * {@link module:engine/conversion/conversion~ConversionHelpers conversion helpers} returned by this function.
 	 *
-	 *		conversion.for( 'downcast' )
+	 *		editor.conversion.for( 'downcast' )
 	 *			.add( conversionHelperA )
-	 *			.add( conversionHelperB );
+	 *			.add( conversionHelperB )
+	 *			.elementToElement( config );
 	 *
 	 * In this example `conversionHelperA` and `conversionHelperB` will be called for all dispatchers from the `'model'` group.
 	 *
@@ -115,15 +118,17 @@ export default class Conversion {
 	 *
 	 * For downcast (model-to-view conversion), these are:
 	 *
-	 * * {@link module:engine/conversion/downcast-converters~_downcastElementToElement Downcast element-to-element converter},
-	 * * {@link module:engine/conversion/downcast-converters~_downcastAttributeToElement Downcast attribute-to-element converter},
-	 * * {@link module:engine/conversion/downcast-converters~_downcastAttributeToAttribute Downcast attribute-to-attribute converter}.
+	 * * {@link module:engine/conversion/downcast-converters~DowncastHelpers#elementToElement Downcast element-to-element converter},
+	 * * {@link module:engine/conversion/downcast-converters~DowncastHelpers#attributeToElement Downcast attribute-to-element converter},
+	 * * {@link module:engine/conversion/downcast-converters~DowncastHelpers#attributeToAttribute Downcast attribute-to-attribute converter}.
+	 * * {@link module:engine/conversion/downcast-converters~DowncastHelpers#markerToElement Downcast marker-to-element converter}.
+	 * * {@link module:engine/conversion/downcast-converters~DowncastHelpers#markerToHighlight Downcast marker-to-highlight converter}.
 	 *
 	 * For upcast (view-to-model conversion), these are:
 	 *
-	 * * {@link module:engine/conversion/upcast-converters~_upcastElementToElement Upcast element-to-element converter},
-	 * * {@link module:engine/conversion/upcast-converters~_upcastElementToAttribute Upcast attribute-to-element converter},
-	 * * {@link module:engine/conversion/upcast-converters~_upcastAttributeToAttribute Upcast attribute-to-attribute converter}.
+	 * * {@link module:engine/conversion/upcast-converters~UpcastHelpers#elementToElement Upcast element-to-element converter},
+	 * * {@link module:engine/conversion/upcast-converters~UpcastHelpers#elementToAttribute Upcast attribute-to-element converter},
+	 * * {@link module:engine/conversion/upcast-converters~UpcastHelpers#attributeToAttribute Upcast attribute-to-attribute converter}.
 	 *
 	 * An example of using conversion helpers to convert the `paragraph` model element to the `p` view element (and back):
 	 *
@@ -131,19 +136,15 @@ export default class Conversion {
 	 *		const config = { model: 'paragraph', view: 'p' };
 	 *
 	 *		// Add converters to proper dispatchers using conversion helpers.
-	 *		conversion.for( 'downcast' ).elementToElement( config ) );
-	 *		conversion.for( 'upcast' ).elementToElement( config ) );
-	 *
-	 * An example of providing a custom conversion helper that uses a custom converter function:
-	 *
-	 *		// Adding a custom `myConverter` converter for 'paragraph' element insertion, with the default priority ('normal').
-	 *		conversion.for( 'downcast' ).add( conversion.customConverter( 'insert:paragraph', myConverter ) );
+	 *		editor.conversion.for( 'downcast' ).elementToElement( config ) );
+	 *		editor.conversion.for( 'upcast' ).elementToElement( config ) );
 	 *
 	 * @param {String} groupName The name of dispatchers group to add the converters to.
 	 * @returns {module:engine/conversion/conversion~ConversionHelpers|module:engine/conversion/downcast-converters~DowncastHelpers|
 	 * module:engine/conversion/upcast-converters~UpcastHelpers}
 	 * An object with the `.add()` method, providing a way to add converters.
 	 */
+	/* eslint-enable max-len */
 	for( groupName ) {
 		const { dispatchers, helpers } = this._getDispatchersGroup( groupName );
 

+ 92 - 206
packages/ckeditor5-engine/src/conversion/downcast-converters.js

@@ -22,27 +22,13 @@ import { cloneDeep } from 'lodash-es';
 /**
  * Model element to view element conversion helper.
  *
- * This conversion results in creating a view element. For example, model `<paragraph>Foo</paragraph>` becomes `<p>Foo</p>` in the view.
+ *		editor.conversion.for( 'downcast' )
+ *			.add( _downcastElementToElement( {
+ *				model: 'paragraph',
+ *				view: 'p'
+ *			} ) );
  *
- *		_downcastElementToElement( { model: 'paragraph', view: 'p' } );
- *
- *		_downcastElementToElement( { model: 'paragraph', view: 'div', converterPriority: 'high' } );
- *
- *		_downcastElementToElement( {
- *			model: 'fancyParagraph',
- *			view: {
- *				name: 'p',
- *				classes: 'fancy'
- *			}
- *		} );
- *
- *		_downcastElementToElement( {
- *			model: 'heading',
- *			view: ( modelElement, viewWriter ) => viewWriter.createContainerElement( 'h' + modelElement.getAttribute( 'level' ) )
- *		} );
- *
- * See {@link module:engine/conversion/conversion~Conversion#for `conversion.for()`} to learn how to add a converter
- * to the conversion process.
+ * The method is publicly available as {@link ~DowncastHelpers#elementToElement `.elementToElement()` downcast helper}.
  *
  * @protected
  * @param {Object} config Conversion configuration.
@@ -65,61 +51,13 @@ export function _downcastElementToElement( config ) {
 /**
  * Model attribute to view element conversion helper.
  *
- * This conversion results in wrapping view nodes with a view attribute element. For example, a model text node with
- * `"Foo"` as data and the `bold` attribute becomes `<strong>Foo</strong>` in the view.
- *
- *		_downcastAttributeToElement( { model: 'bold', view: 'strong' } );
- *
- *		_downcastAttributeToElement( { model: 'bold', view: 'b', converterPriority: 'high' } );
- *
- *		_downcastAttributeToElement( {
- *			model: 'invert',
- *			view: {
- *				name: 'span',
- *				classes: [ 'font-light', 'bg-dark' ]
- *			}
- *		} );
- *
- *		_downcastAttributeToElement( {
- *			model: {
- *				key: 'fontSize',
- *				values: [ 'big', 'small' ]
- *			},
- *			view: {
- *				big: {
- *					name: 'span',
- *					styles: {
- *						'font-size': '1.2em'
- *					}
- *				},
- *				small: {
- *					name: 'span',
- *					styles: {
- *						'font-size': '0.8em'
- *					}
- *				}
- *			}
- *		} );
- *
- *		_downcastAttributeToElement( {
- *			model: 'bold',
- *				view: ( modelAttributeValue, viewWriter ) => {
- *				return viewWriter.createAttributeElement( 'span', { style: 'font-weight:' + modelAttributeValue } );
- *			}
- *		} );
- *
- *		_downcastAttributeToElement( {
- *			model: {
- *				key: 'color',
- *				name: '$text'
- *			},
- *			view: ( modelAttributeValue, viewWriter ) => {
- *				return viewWriter.createAttributeElement( 'span', { style: 'color:' + modelAttributeValue } );
- *			}
- *		} );
+ *		editor.conversion.for( 'downcast' )
+ *			.add( _downcastAttributeToElement( {
+ *				model: 'bold',
+ *				view: 'strong'
+ *			} ) );
  *
- * See {@link module:engine/conversion/conversion~Conversion#for `conversion.for()`} to learn how to add a converter
- * to the conversion process.
+ * The method is publicly available as {@link ~DowncastHelpers#attributeToElement `.attributeToElement()` downcast helper}.
  *
  * @protected
  * @param {Object} config Conversion configuration.
@@ -160,45 +98,13 @@ export function _downcastAttributeToElement( config ) {
 /**
  * Model attribute to view attribute conversion helper.
  *
- * This conversion results in adding an attribute to a view node, basing on an attribute from a model node. For example,
- * `<image src='foo.jpg'></image>` is converted to `<img src='foo.jpg'></img>`.
- *
- *		_downcastAttributeToAttribute( { model: 'source', view: 'src' } );
- *
- *		_downcastAttributeToAttribute( { model: 'source', view: 'href', converterPriority: 'high' } );
- *
- *		_downcastAttributeToAttribute( {
- *			model: {
- *				name: 'image',
- *				key: 'source'
- *			},
- *			view: 'src'
- *		} );
+ *		editor.conversion.for( 'downcast' )
+ *			.add( _downcastAttributeToAttribute( {
+ *				model: 'source',
+ *				view: 'src'
+ *			} ) );
  *
- *		_downcastAttributeToAttribute( {
- *			model: {
- *				name: 'styled',
- *				values: [ 'dark', 'light' ]
- *			},
- *			view: {
- *				dark: {
- *					key: 'class',
- *					value: [ 'styled', 'styled-dark' ]
- *				},
- *				light: {
- *					key: 'class',
- *					value: [ 'styled', 'styled-light' ]
- *				}
- *			}
- *		} );
- *
- *		_downcastAttributeToAttribute( {
- *			model: 'styled',
- *			view: modelAttributeValue => ( { key: 'class', value: 'styled-' + modelAttributeValue } )
- *		} );
- *
- * See {@link module:engine/conversion/conversion~Conversion#for `conversion.for()`} to learn how to add a converter
- * to the conversion process.
+ * The method is publicly available as {@link ~DowncastHelpers#attributeToAttribute `.attributeToAttribute()` downcast helper}.
  *
  * @protected
  * @param {Object} config Conversion configuration.
@@ -240,41 +146,13 @@ export function _downcastAttributeToAttribute( config ) {
 /**
  * Model marker to view element conversion helper.
  *
- * This conversion results in creating a view element on the boundaries of the converted marker. If the converted marker
- * is collapsed, only one element is created. For example, model marker set like this: `<paragraph>F[oo b]ar</paragraph>`
- * becomes `<p>F<span data-marker="search"></span>oo b<span data-marker="search"></span>ar</p>` in the view.
- *
- *		_downcastMarkerToElement( { model: 'search', view: 'marker-search' } );
- *
- *		_downcastMarkerToElement( { model: 'search', view: 'search-result', converterPriority: 'high' } );
- *
- *		_downcastMarkerToElement( {
- *			model: 'search',
- *			view: {
- *				name: 'span',
- *				attributes: {
- *					'data-marker': 'search'
- *				}
- *			}
- *		} );
- *
- *		_downcastMarkerToElement( {
- *			model: 'search',
- *			view: ( markerData, viewWriter ) => {
- *			return viewWriter.createUIElement( 'span', { 'data-marker': 'search', 'data-start': markerData.isOpening } );
- *			}
- *		} );
- *
- * 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/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.
- *
- * This kind of conversion is useful for saving data into the database, so it should be used in the data conversion pipeline.
+ *		editor.conversion.for( 'downcast' )
+ *			.add( _downcastMarkerToElement( {
+ *				model: 'search',
+ *				view: 'marker-search'
+ *			} ) );
  *
- * See {@link module:engine/conversion/conversion~Conversion#for} to learn how to add a converter to the conversion process.
+ * The method is publicly available as {@link ~DowncastHelpers#markerToElement `.markerToElement()` downcast helper}.
  *
  * @protected
  * @param {Object} config Conversion configuration.
@@ -298,44 +176,13 @@ export function _downcastMarkerToElement( config ) {
 /**
  * Model marker to highlight conversion helper.
  *
- * This conversion results in creating a highlight on view nodes. For this kind of conversion,
- * {@link module:engine/conversion/downcast-converters~HighlightDescriptor} should be provided.
- *
- * For text nodes, a `<span>` {@link module:engine/view/attributeelement~AttributeElement} is created and it wraps all text nodes
- * in the converted marker range. For example, a model marker set like this: `<paragraph>F[oo b]ar</paragraph>` becomes
- * `<p>F<span class="comment">oo b</span>ar</p>` in the view.
- *
- * {@link module:engine/view/containerelement~ContainerElement} may provide a custom way of handling highlight. Most often,
- * the element itself is given classes and attributes described in the highlight descriptor (instead of being wrapped in `<span>`).
- * For example, a model marker set like this: `[<image src="foo.jpg"></image>]` becomes `<img src="foo.jpg" class="comment"></img>`
- * in the view.
- *
- * For container elements, the conversion is two-step. While the converter processes the highlight descriptor and passes it
- * to a container element, it is the container element instance itself that applies values from the highlight descriptor.
- * So, in a sense, the converter takes care of stating what should be applied on what, while the element decides how to apply that.
+ *		editor.conversion.for( 'downcast' )
+ *			.add( _downcastMarkerToHighlight( {
+ *				model: 'comment',
+ *				view: { classes: 'comment' }
+ *			} ) );
  *
- *		downcastMarkerToHighlight( { model: 'comment', view: { classes: 'comment' } } );
- *
- *		downcastMarkerToHighlight( { model: 'comment', view: { classes: 'new-comment' }, converterPriority: 'high' } );
- *
- *		downcastMarkerToHighlight( {
- *			model: 'comment',
- *			view: data => {
- *				// Assuming that the marker name is in a form of comment:commentType.
- *				const commentType = data.markerName.split( ':' )[ 1 ];
- *
- *				return {
- *					classes: [ 'comment', 'comment-' + commentType ]
- *				};
- *			}
- *		} );
- *
- * If a function is passed as the `config.view` parameter, it will be used to generate the highlight descriptor. The function
- * receives the `data` object as a parameter and should return a
- * {@link module:engine/conversion/downcast-converters~HighlightDescriptor highlight descriptor}.
- * The `data` object properties are passed from {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:addMarker}.
- *
- * See {@link module:engine/conversion/conversion~Conversion#for} to learn how to add a converter to the conversion process.
+ * The method is publicly available as {@link ~DowncastHelpers#markerToElement `.markerToElement()` downcast helper}.
  *
  * @protected
  * @param {Object} config Conversion configuration.
@@ -715,7 +562,7 @@ export function changeAttribute( attributeCreator ) {
 			 * {@link module:engine/conversion/conversion~Conversion#attributeToElement `Attribute to Element converter`}
 			 * with higher {@link module:utils/priorities~PriorityString priority} must also be defined:
 			 *
-			 *		conversion.for( 'downcast' ).attributeToElement( {
+			 *		editor.conversion.for( 'downcast' ).attributeToElement( {
 			 *			model: {
 			 *				key: 'attribute-name',
 			 *				name: '$text'
@@ -1121,9 +968,16 @@ export const helpers = {
 	 *
 	 * This conversion results in creating a view element. For example, model `<paragraph>Foo</paragraph>` becomes `<p>Foo</p>` in the view.
 	 *
-	 *		editor.conversion.for( 'downcast' ).elementToElement( { model: 'paragraph', view: 'p' } );
+	 *		editor.conversion.for( 'downcast' ).elementToElement( {
+	 *			model: 'paragraph',
+	 *			view: 'p'
+	 *		} );
 	 *
-	 *		editor.conversion.for( 'downcast' ).elementToElement( { model: 'paragraph', view: 'div', converterPriority: 'high' } );
+	 *		editor.conversion.for( 'downcast' ).elementToElement( {
+	 *			model: 'paragraph',
+	 *			view: 'div',
+	 *			converterPriority: 'high'
+	 *		} );
 	 *
 	 *		editor.conversion.for( 'downcast' ).elementToElement( {
 	 *			model: 'fancyParagraph',
@@ -1135,7 +989,9 @@ export const helpers = {
 	 *
 	 *		editor.conversion.for( 'downcast' ).elementToElement( {
 	 *			model: 'heading',
-	 *			view: ( modelElement, viewWriter ) => viewWriter.createContainerElement( 'h' + modelElement.getAttribute( 'level' ) )
+	 *			view: ( modelElement, viewWriter ) => {
+	 *				return viewWriter.createContainerElement( 'h' + modelElement.getAttribute( 'level' ) )
+	 *			}
 	 *		} );
 	 *
 	 * See {@link module:engine/conversion/conversion~Conversion#for `conversion.for()`} to learn how to add a converter
@@ -1159,9 +1015,16 @@ export const helpers = {
 	 * This conversion results in wrapping view nodes with a view attribute element. For example, a model text node with
 	 * `"Foo"` as data and the `bold` attribute becomes `<strong>Foo</strong>` in the view.
 	 *
-	 *		editor.conversion.for( 'downcast' ).attributeToElement( { model: 'bold', view: 'strong' } );
+	 *		editor.conversion.for( 'downcast' ).attributeToElement( {
+	 *			model: 'bold',
+	 *			view: 'strong'
+	 *		} );
 	 *
-	 *		editor.conversion.for( 'downcast' ).attributeToElement( { model: 'bold', view: 'b', converterPriority: 'high' } );
+	 *		editor.conversion.for( 'downcast' ).attributeToElement( {
+	 *			model: 'bold',
+	 *			view: 'b',
+	 *			converterPriority: 'high'
+	 *		} );
 	 *
 	 *		editor.conversion.for( 'downcast' ).attributeToElement( {
 	 *			model: 'invert',
@@ -1195,7 +1058,9 @@ export const helpers = {
 	 *		editor.conversion.for( 'downcast' ).attributeToElement( {
 	 *			model: 'bold',
 	 *			view: ( modelAttributeValue, viewWriter ) => {
-	 *				return viewWriter.createAttributeElement( 'span', { style: 'font-weight:' + modelAttributeValue } );
+	 *				return viewWriter.createAttributeElement( 'span', {
+	 *					style: 'font-weight:' + modelAttributeValue
+	 *				} );
 	 *			}
 	 *		} );
 	 *
@@ -1205,7 +1070,9 @@ export const helpers = {
 	 *				name: '$text'
 	 *			},
 	 *			view: ( modelAttributeValue, viewWriter ) => {
-	 *				return viewWriter.createAttributeElement( 'span', { style: 'color:' + modelAttributeValue } );
+	 *				return viewWriter.createAttributeElement( 'span', {
+	 *					style: 'color:' + modelAttributeValue
+	 *				} );
 	 *			}
 	 *		} );
 	 *
@@ -1232,11 +1099,18 @@ export const helpers = {
 	 * This conversion results in adding an attribute to a view node, basing on an attribute from a model node. For example,
 	 * `<image src='foo.jpg'></image>` is converted to `<img src='foo.jpg'></img>`.
 	 *
-	 *		conversion.for( 'downcast' ).attributeToAttribute( { model: 'source', view: 'src' } );
+	 *		editor.conversion.for( 'downcast' ).attributeToAttribute( {
+	 *			model: 'source',
+	 *			view: 'src'
+	 *		} );
 	 *
-	 *		conversion.for( 'downcast' ).attributeToAttribute( { model: 'source', view: 'href', converterPriority: 'high' } );
+	 *		editor.conversion.for( 'downcast' ).attributeToAttribute( {
+	 *			model: 'source',
+	 *			view: 'href',
+	 *			converterPriority: 'high'
+	 *		} );
 	 *
-	 *		conversion.for( 'downcast' ).attributeToAttribute( {
+	 *		editor.conversion.for( 'downcast' ).attributeToAttribute( {
 	 *			model: {
 	 *				name: 'image',
 	 *				key: 'source'
@@ -1244,7 +1118,7 @@ export const helpers = {
 	 *			view: 'src'
 	 *		} );
 	 *
-	 *		conversion.for( 'downcast' ).attributeToAttribute( {
+	 *		editor.conversion.for( 'downcast' ).attributeToAttribute( {
 	 *			model: {
 	 *				name: 'styled',
 	 *				values: [ 'dark', 'light' ]
@@ -1261,7 +1135,7 @@ export const helpers = {
 	 *			}
 	 *		} );
 	 *
-	 *		conversion.for( 'downcast' ).attributeToAttribute( {
+	 *		editor.conversion.for( 'downcast' ).attributeToAttribute( {
 	 *			model: 'styled',
 	 *			view: modelAttributeValue => ( { key: 'class', value: 'styled-' + modelAttributeValue } )
 	 *		} );
@@ -1292,11 +1166,18 @@ export const helpers = {
 	 * is collapsed, only one element is created. For example, model marker set like this: `<paragraph>F[oo b]ar</paragraph>`
 	 * becomes `<p>F<span data-marker="search"></span>oo b<span data-marker="search"></span>ar</p>` in the view.
 	 *
-	 *		conversion.for( 'downcast' ).markerToElement( { model: 'search', view: 'marker-search' } );
+	 *		editor.conversion.for( 'downcast' ).markerToElement( {
+	 *			model: 'search',
+	 *			view: 'marker-search'
+	 *		} );
 	 *
-	 *		conversion.for( 'downcast' ).markerToElement( { model: 'search', view: 'search-result', converterPriority: 'high' } );
+	 *		editor.conversion.for( 'downcast' ).markerToElement( {
+	 *			model: 'search',
+	 *			view: 'search-result',
+	 *			converterPriority: 'high'
+	 *		} );
 	 *
-	 *		conversion.for( 'downcast' ).markerToElement( {
+	 *		editor.conversion.for( 'downcast' ).markerToElement( {
 	 *			model: 'search',
 	 *			view: {
 	 *				name: 'span',
@@ -1306,10 +1187,13 @@ export const helpers = {
 	 *			}
 	 *		} );
 	 *
-	 *		conversion.for( 'downcast' ).markerToElement( {
+	 *		editor.conversion.for( 'downcast' ).markerToElement( {
 	 *			model: 'search',
 	 *			view: ( markerData, viewWriter ) => {
-	 *			return viewWriter.createUIElement( 'span', { 'data-marker': 'search', 'data-start': markerData.isOpening } );
+	 *				return viewWriter.createUIElement( 'span', {
+	 *					'data-marker': 'search',
+	 *					'data-start': markerData.isOpening
+	 *				} );
 	 *			}
 	 *		} );
 	 *
@@ -1322,7 +1206,8 @@ export const helpers = {
 	 *
 	 * This kind of conversion is useful for saving data into the database, so it should be used in the data conversion pipeline.
 	 *
-	 * See {@link module:engine/conversion/conversion~Conversion#for} to learn how to add a converter to the conversion process.
+	 * See {@link module:engine/conversion/conversion~Conversion#for `conversion.for()`} to learn how to add a converter
+	 * to the conversion process.
 	 *
 	 * @method #markerToElement
 	 * @param {Object} config Conversion configuration.
@@ -1355,15 +1240,15 @@ export const helpers = {
 	 * to a container element, it is the container element instance itself that applies values from the highlight descriptor.
 	 * So, in a sense, the converter takes care of stating what should be applied on what, while the element decides how to apply that.
 	 *
-	 *		conversion.for( 'downcast' ).markerToHighlight( { model: 'comment', view: { classes: 'comment' } } );
+	 *		editor.conversion.for( 'downcast' ).markerToHighlight( { model: 'comment', view: { classes: 'comment' } } );
 	 *
-	 *		conversion.for( 'downcast' ).markerToHighlight( {
+	 *		editor.conversion.for( 'downcast' ).markerToHighlight( {
 	 *			model: 'comment',
 	 *			view: { classes: 'new-comment' },
 	 *			converterPriority: 'high'
 	 *		} );
 	 *
-	 *		conversion.for( 'downcast' ).markerToHighlight( {
+	 *		editor.conversion.for( 'downcast' ).markerToHighlight( {
 	 *			model: 'comment',
 	 *			view: data => {
 	 *				// Assuming that the marker name is in a form of comment:commentType.
@@ -1380,7 +1265,8 @@ export const helpers = {
 	 * {@link module:engine/conversion/downcast-converters~HighlightDescriptor highlight descriptor}.
 	 * The `data` object properties are passed from {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:addMarker}.
 	 *
-	 * See {@link module:engine/conversion/conversion~Conversion#for} to learn how to add a converter to the conversion process.
+	 * See {@link module:engine/conversion/conversion~Conversion#for `conversion.for()`} to learn how to add a converter
+	 * to the conversion process.
 	 *
 	 * @method #markerToHighlight
 	 * @param {Object} config Conversion configuration.

+ 87 - 194
packages/ckeditor5-engine/src/conversion/upcast-converters.js

@@ -19,33 +19,13 @@ import { cloneDeep } from 'lodash-es';
 /**
  * View element to model element conversion helper.
  *
- * This conversion results in creating a model element. For example, view `<p>Foo</p>` becomes `<paragraph>Foo</paragraph>` in the model.
+ *		editor.conversion.for( 'upcast' )
+ *			.add( _upcastElementToElement( {
+ *				view: 'p',
+ *				model: 'paragraph'
+ *			} ) );
  *
- * Keep in mind that the element will be inserted only if it is allowed by {@link module:engine/model/schema~Schema schema} configuration.
- *
- *		_upcastElementToElement( { view: 'p', model: 'paragraph' } );
- *
- *		_upcastElementToElement( { view: 'p', model: 'paragraph', converterPriority: 'high' } );
- *
- *		_upcastElementToElement( {
- *			view: {
- *				name: 'p',
- *				classes: 'fancy'
- *			},
- *			model: 'fancyParagraph'
- *		} );
- *
- *		_upcastElementToElement( {
- * 			view: {
- *				name: 'p',
- *				classes: 'heading'
- * 			},
- * 			model: ( viewElement, modelWriter ) => {
- * 				return modelWriter.createElement( 'heading', { level: viewElement.getAttribute( 'data-level' ) } );
- * 			}
- * 		} );
- *
- * See {@link module:engine/conversion/conversion~Conversion#for} to learn how to add converter to conversion process.
+ * The method is publicly available as {@link ~UpcastHelpers#elementToElement `.elementToElement()` upcast helper}.
  *
  * @param {Object} config Conversion configuration.
  * @param {module:engine/view/matcher~MatcherPattern} config.view Pattern matching all view elements which should be converted.
@@ -70,67 +50,13 @@ export function _upcastElementToElement( config ) {
 /**
  * View element to model attribute conversion helper.
  *
- * This conversion results in setting an attribute on a model node. For example, view `<strong>Foo</strong>` becomes
- * `Foo` {@link module:engine/model/text~Text model text node} with `bold` attribute set to `true`.
- *
- * This helper is meant to set a model attribute on all the elements that are inside the converted element:
- *
- *		<strong>Foo</strong>   -->   <strong><p>Foo</p></strong>   -->   <paragraph><$text bold="true">Foo</$text></paragraph>
- *
- * Above is a sample of HTML code, that goes through autoparagraphing (first step) and then is converted (second step).
- * Even though `<strong>` is over `<p>` element, `bold="true"` was added to the text. See
- * {@link module:engine/conversion/upcast-converters~upcastAttributeToAttribute} for comparison.
- *
- * Keep in mind that the attribute will be set only if it is allowed by {@link module:engine/model/schema~Schema schema} configuration.
- *
- *		_upcastElementToAttribute( { view: 'strong', model: 'bold' } );
- *
- *		_upcastElementToAttribute( { view: 'strong', model: 'bold', converterPriority: 'high' } );
- *
- *		_upcastElementToAttribute( {
- *			view: {
- *				name: 'span',
- *				classes: 'bold'
- *			},
- *			model: 'bold'
- *		} );
+ *		editor.conversion.for( 'upcast' )
+ *			.add( _upcastElementToAttribute( {
+ *				view: 'strong',
+ *				model: 'bold'
+ *			} ) );
  *
- *		_upcastElementToAttribute( {
- *			view: {
- *				name: 'span',
- *				classes: [ 'styled', 'styled-dark' ]
- *			},
- *			model: {
- *				key: 'styled',
- *				value: 'dark'
- *			}
- *		} );
- *
- * 		_upcastElementToAttribute( {
- *			view: {
- *				name: 'span',
- *				styles: {
- *					'font-size': /[\s\S]+/
- *				}
- *			},
- *			model: {
- *				key: 'fontSize',
- *				value: viewElement => {
- *					const fontSize = viewElement.getStyle( 'font-size' );
- *					const value = fontSize.substr( 0, fontSize.length - 2 );
- *
- *					if ( value <= 10 ) {
- *						return 'small';
- *					} else if ( value > 12 ) {
- *						return 'big';
- *					}
- *
- *					return null;
- *				}
- *			}
- *		} );
- *
- * See {@link module:engine/conversion/conversion~Conversion#for} to learn how to add converter to conversion process.
+ * The method is publicly available as {@link ~UpcastHelpers#elementToAttribute `.elementToAttribute()` upcast helper}.
  *
  * @param {Object} config Conversion configuration.
  * @param {module:engine/view/matcher~MatcherPattern} config.view Pattern matching all view elements which should be converted.
@@ -158,67 +84,13 @@ export function _upcastElementToAttribute( config ) {
 /**
  * View attribute to model attribute conversion helper.
  *
- * This conversion results in setting an attribute on a model node. For example, view `<img src="foo.jpg"></img>` becomes
- * `<image source="foo.jpg"></image>` in the model.
- *
- * This helper is meant to convert view attributes from view elements which got converted to the model, so the view attribute
- * is set only on the corresponding model node:
- *
- *		<div class="dark"><div>foo</div></div>    -->    <div dark="true"><div>foo</div></div>
- *
- * Above, `class="dark"` attribute is added only to the `<div>` elements that has it. This is in contrary to
- * {@link module:engine/conversion/upcast-converters~upcastElementToAttribute} which sets attributes for all the children in the model:
- *
- *		<strong>Foo</strong>   -->   <strong><p>Foo</p></strong>   -->   <paragraph><$text bold="true">Foo</$text></paragraph>
- *
- * Above is a sample of HTML code, that goes through autoparagraphing (first step) and then is converted (second step).
- * Even though `<strong>` is over `<p>` element, `bold="true"` was added to the text.
- *
- * Keep in mind that the attribute will be set only if it is allowed by {@link module:engine/model/schema~Schema schema} configuration.
- *
- *		_upcastAttributeToAttribute( { view: 'src', model: 'source' } );
+ *		editor.conversion.for( 'upcast' )
+ *			.add( _upcastAttributeToAttribute( {
+ *				view: 'src',
+ *				model: 'source'
+ *			} ) );
  *
- *		_upcastAttributeToAttribute( { view: { key: 'src' }, model: 'source' } );
- *
- *		_upcastAttributeToAttribute( { view: { key: 'src' }, model: 'source', converterPriority: 'normal' } );
- *
- *		_upcastAttributeToAttribute( {
- *			view: {
- *				key: 'data-style',
- *				value: /[\s\S]+/
- *			},
- *			model: 'styled'
- *		} );
- *
- *		_upcastAttributeToAttribute( {
- *			view: {
- *				name: 'img',
- *				key: 'class',
- *				value: 'styled-dark'
- *			},
- *			model: {
- *				key: 'styled',
- *				value: 'dark'
- *			}
- *		} );
- *
- *		_upcastAttributeToAttribute( {
- *			view: {
- *				key: 'class',
- *				value: /styled-[\S]+/
- *			},
- *			model: {
- *				key: 'styled'
- *				value: viewElement => {
- *					const regexp = /styled-([\S]+)/;
- *					const match = viewElement.getAttribute( 'class' ).match( regexp );
- *
- *					return match[ 1 ];
- *				}
- *			}
- *		} );
- *
- * See {@link module:engine/conversion/conversion~Conversion#for} to learn how to add converter to conversion process.
+ * The method is publicly available as {@link ~UpcastHelpers#attributeToAttribute `.attributeToAttribute()` upcast helper}.
  *
  * @param {Object} config Conversion configuration.
  * @param {String|Object} config.view Specifies which view attribute will be converted. If a `String` is passed,
@@ -253,31 +125,13 @@ export function _upcastAttributeToAttribute( config ) {
 /**
  * View element to model marker conversion helper.
  *
- * This conversion results in creating a model marker. For example, if the marker was stored in a view as an element:
- * `<p>Fo<span data-marker="comment" data-comment-id="7"></span>o</p><p>B<span data-marker="comment" data-comment-id="7"></span>ar</p>`,
- * after the conversion is done, the marker will be available in
- * {@link module:engine/model/model~Model#markers model document markers}.
+ *		editor.conversion.for( 'upcast' )
+ *			.add( _upcastElementToMarker( {
+ *				view: 'marker-search',
+ *				model: 'search'
+ *			} ) );
  *
- *		_upcastElementToMarker( { view: 'marker-search', model: 'search' } );
- *
- *		_upcastElementToMarker( { view: 'marker-search', model: 'search', converterPriority: 'high' } );
- *
- *		_upcastElementToMarker( {
- *			view: 'marker-search',
- *			model: viewElement => 'comment:' + viewElement.getAttribute( 'data-comment-id' )
- *		} );
- *
- *		_upcastElementToMarker( {
- *			view: {
- *				name: 'span',
- *				attributes: {
- *					'data-marker': 'search'
- *				}
- *			},
- *			model: 'search'
- *		} );
- *
- * See {@link module:engine/conversion/conversion~Conversion#for} to learn how to add converter to conversion process.
+ * The method is publicly available as {@link ~UpcastHelpers#elementToMarker `.elementToMarker()` upcast helper}.
  *
  * @param {Object} config Conversion configuration.
  * @param {module:engine/view/matcher~MatcherPattern} config.view Pattern matching all view elements which should be converted.
@@ -624,11 +478,18 @@ export const helpers = {
 	 * Keep in mind that the element will be inserted only if it is allowed
 	 * by {@link module:engine/model/schema~Schema schema} configuration.
 	 *
-	 *		conversion.for( 'upcast' ).elementToElement( { view: 'p', model: 'paragraph' } );
+	 *		editor.conversion.for( 'upcast' ).elementToElement( {
+	 *			view: 'p',
+	 *			model: 'paragraph'
+	 *		} );
 	 *
-	 *		conversion.for( 'upcast' ).elementToElement( { view: 'p', model: 'paragraph', converterPriority: 'high' } );
+	 *		editor.conversion.for( 'upcast' ).elementToElement( {
+	 *			view: 'p',
+	 *			model: 'paragraph',
+	 *			converterPriority: 'high'
+	 *		} );
 	 *
-	 *		conversion.for( 'upcast' ).elementToElement( {
+	 *		editor.conversion.for( 'upcast' ).elementToElement( {
 	 *			view: {
 	 *				name: 'p',
 	 *				classes: 'fancy'
@@ -636,7 +497,7 @@ export const helpers = {
 	 *			model: 'fancyParagraph'
 	 *		} );
 	 *
-	 *		conversion.for( 'upcast' ).elementToElement( {
+	 *		editor.conversion.for( 'upcast' ).elementToElement( {
 	 * 			view: {
 	 *				name: 'p',
 	 *				classes: 'heading'
@@ -646,7 +507,8 @@ export const helpers = {
 	 * 			}
 	 * 		} );
 	 *
-	 * See {@link module:engine/conversion/conversion~Conversion#for} to learn how to add converter to conversion process.
+	 * See {@link module:engine/conversion/conversion~Conversion#for `conversion.for()`} to learn how to add a converter
+	 * to the conversion process.
 	 *
 	 * @method #elementToElement
 	 * @param {Object} config Conversion configuration.
@@ -676,11 +538,18 @@ export const helpers = {
 	 *
 	 * Keep in mind that the attribute will be set only if it is allowed by {@link module:engine/model/schema~Schema schema} configuration.
 	 *
-	 *		conversion.for( 'upcast' ).elementToAttribute( { view: 'strong', model: 'bold' } );
+	 *		editor.conversion.for( 'upcast' ).elementToAttribute( {
+	 *			view: 'strong',
+	 *			model: 'bold'
+	 *		} );
 	 *
-	 *		conversion.for( 'upcast' ).elementToAttribute( { view: 'strong', model: 'bold', converterPriority: 'high' } );
+	 *		editor.conversion.for( 'upcast' ).elementToAttribute( {
+	 *			view: 'strong',
+	 *			model: 'bold',
+	 *			converterPriority: 'high'
+	 *		} );
 	 *
-	 *		conversion.for( 'upcast' ).elementToAttribute( {
+	 *		editor.conversion.for( 'upcast' ).elementToAttribute( {
 	 *			view: {
 	 *				name: 'span',
 	 *				classes: 'bold'
@@ -688,7 +557,7 @@ export const helpers = {
 	 *			model: 'bold'
 	 *		} );
 	 *
-	 *		conversion.for( 'upcast' ).elementToAttribute( {
+	 *		editor.conversion.for( 'upcast' ).elementToAttribute( {
 	 *			view: {
 	 *				name: 'span',
 	 *				classes: [ 'styled', 'styled-dark' ]
@@ -699,7 +568,7 @@ export const helpers = {
 	 *			}
 	 *		} );
 	 *
-	 * 		conversion.for( 'upcast' ).elementToAttribute( {
+	 * 		editor.conversion.for( 'upcast' ).elementToAttribute( {
 	 *			view: {
 	 *				name: 'span',
 	 *				styles: {
@@ -723,8 +592,10 @@ export const helpers = {
 	 *			}
 	 *		} );
 	 *
-	 * See {@link module:engine/conversion/conversion~Conversion#for} to learn how to add converter to conversion process.
+	 * See {@link module:engine/conversion/conversion~Conversion#for `conversion.for()`} to learn how to add a converter
+	 * to the conversion process.
 	 *
+	 * @method #elementToAttribute
 	 * @param {Object} config Conversion configuration.
 	 * @param {module:engine/view/matcher~MatcherPattern} config.view Pattern matching all view elements which should be converted.
 	 * @param {String|Object} config.model Model attribute key or an object with `key` and `value` properties, describing
@@ -749,7 +620,8 @@ export const helpers = {
 	 *		<div class="dark"><div>foo</div></div>    -->    <div dark="true"><div>foo</div></div>
 	 *
 	 * Above, `class="dark"` attribute is added only to the `<div>` elements that has it. This is in contrary to
-	 * {@link module:engine/conversion/upcast-converters~upcastElementToAttribute} which sets attributes for all the children in the model:
+	 * {@link module:engine/conversion/upcast-converters~UpcastHelpers#elementToAttribute} which sets attributes for
+	 * all the children in the model:
 	 *
 	 *		<strong>Foo</strong>   -->   <strong><p>Foo</p></strong>   -->   <paragraph><$text bold="true">Foo</$text></paragraph>
 	 *
@@ -758,13 +630,23 @@ export const helpers = {
 	 *
 	 * Keep in mind that the attribute will be set only if it is allowed by {@link module:engine/model/schema~Schema schema} configuration.
 	 *
-	 *		conversion.for( 'upcast' ).attributeToAttribute( { view: 'src', model: 'source' } );
+	 *		editor.conversion.for( 'upcast' ).attributeToAttribute( {
+	 *			view: 'src',
+	 *			model: 'source'
+	 *		} );
 	 *
-	 *		conversion.for( 'upcast' ).attributeToAttribute( { view: { key: 'src' }, model: 'source' } );
+	 *		editor.conversion.for( 'upcast' ).attributeToAttribute( {
+	 *			view: { key: 'src' },
+	 *			model: 'source'
+	 *		} );
 	 *
-	 *		conversion.for( 'upcast' ).attributeToAttribute( { view: { key: 'src' }, model: 'source', converterPriority: 'normal' } );
+	 *		editor.conversion.for( 'upcast' ).attributeToAttribute( {
+	 *			view: { key: 'src' },
+	 *			model: 'source',
+	 *			converterPriority: 'normal'
+	 *		} );
 	 *
-	 *		conversion.for( 'upcast' ).attributeToAttribute( {
+	 *		editor.conversion.for( 'upcast' ).attributeToAttribute( {
 	 *			view: {
 	 *				key: 'data-style',
 	 *				value: /[\s\S]+/
@@ -772,7 +654,7 @@ export const helpers = {
 	 *			model: 'styled'
 	 *		} );
 	 *
-	 *		conversion.for( 'upcast' ).attributeToAttribute( {
+	 *		editor.conversion.for( 'upcast' ).attributeToAttribute( {
 	 *			view: {
 	 *				name: 'img',
 	 *				key: 'class',
@@ -784,7 +666,7 @@ export const helpers = {
 	 *			}
 	 *		} );
 	 *
-	 *		conversion.for( 'upcast' ).attributeToAttribute( {
+	 *		editor.conversion.for( 'upcast' ).attributeToAttribute( {
 	 *			view: {
 	 *				key: 'class',
 	 *				value: /styled-[\S]+/
@@ -800,8 +682,10 @@ export const helpers = {
 	 *			}
 	 *		} );
 	 *
-	 * See {@link module:engine/conversion/conversion~Conversion#for} to learn how to add converter to conversion process.
+	 * See {@link module:engine/conversion/conversion~Conversion#for `conversion.for()`} to learn how to add a converter
+	 * to the conversion process.
 	 *
+	 * @method #attributeToAttribute
 	 * @param {Object} config Conversion configuration.
 	 * @param {String|Object} config.view Specifies which view attribute will be converted. If a `String` is passed,
 	 * attributes with given key will be converted. If an `Object` is passed, it must have a required `key` property,
@@ -826,16 +710,23 @@ export const helpers = {
 	 * after the conversion is done, the marker will be available in
 	 * {@link module:engine/model/model~Model#markers model document markers}.
 	 *
-	 *		conversion.for( 'upcast' ).elementToMarker( { view: 'marker-search', model: 'search' } );
+	 *		editor.conversion.for( 'upcast' ).elementToMarker( {
+	 *			view: 'marker-search',
+	 *			model: 'search'
+	 *		} );
 	 *
-	 *		conversion.for( 'upcast' ).elementToMarker( { view: 'marker-search', model: 'search', converterPriority: 'high' } );
+	 *		editor.conversion.for( 'upcast' ).elementToMarker( {
+	 *			view: 'marker-search',
+	 *			model: 'search',
+	 *			converterPriority: 'high'
+	 *		} );
 	 *
-	 *		conversion.for( 'upcast' ).elementToMarker( {
+	 *		editor.conversion.for( 'upcast' ).elementToMarker( {
 	 *			view: 'marker-search',
 	 *			model: viewElement => 'comment:' + viewElement.getAttribute( 'data-comment-id' )
 	 *		} );
 	 *
-	 *		conversion.for( 'upcast' ).elementToMarker( {
+	 *		editor.conversion.for( 'upcast' ).elementToMarker( {
 	 *			view: {
 	 *				name: 'span',
 	 *				attributes: {
@@ -845,8 +736,10 @@ export const helpers = {
 	 *			model: 'search'
 	 *		} );
 	 *
-	 * See {@link module:engine/conversion/conversion~Conversion#for} to learn how to add converter to conversion process.
+	 * See {@link module:engine/conversion/conversion~Conversion#for `conversion.for()`} to learn how to add a converter
+	 * to the conversion process.
 	 *
+	 * @method #elementToMarker
 	 * @param {Object} config Conversion configuration.
 	 * @param {module:engine/view/matcher~MatcherPattern} config.view Pattern matching all view elements which should be converted.
 	 * @param {String|Function} config.model Name of the model marker, or a function that takes a view element and returns