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

Docs: Improved conversion manager's docs.

Piotrek Koszuliński 7 лет назад
Родитель
Сommit
e03916db6c

+ 39 - 1
packages/ckeditor5-engine/src/conversion/conversion.js

@@ -22,7 +22,45 @@ import {
 } from './upcast-converters';
 
 /**
- * An utility class that helps organizing dispatchers and adding converters to them.
+ * An utility class that helps adding converters to upcast and downcast dispatchers.
+ *
+ * We recommend reading first the {@glink framework/guides/architecture/editing-engine} guide to understand the
+ * core concepts of the conversion mechanisms.
+ *
+ * The instance of the conversion manager is available in the
+ * {@link module:core/editor/editor~Editor#conversion `editor.conversion`} property
+ * and by default has the following groups of dispatchers (i.e. directions of conversion):
+ *
+ * * `downcast` (editing and data downcasts)
+ * * `editingDowncast`
+ * * `dataDowncast`
+ * * `upcast`
+ *
+ * To add a converter to a specific group use the {@link module:engine/conversion/conversion~Conversion#for `for()`}
+ * method:
+ *
+ *		// Add a converter to editing downcast and data downcast.
+ *		editor.conversion.for( 'downcast' ).add( downcastElementToElement( config ) );
+ *
+ *		// Add a converter to the data pipepline only:
+ *		editor.conversion.for( 'dataDowncast' ).add( downcastElementToElement( config ) );
+ *		// And a slightly different one for the editing pipeline:
+ *		editor.conversion.for( 'editingDowncast' ).add( downcastElementToWidget( config ) );
+ *
+ * The functions used in `add()` calls are one-way converters (i.e. you need to remember yourself to add
+ * a converter in the other direction, if you feature requires that). They are also called "conversion helpers".
+ * You can find a set of them in the {@link module:engine/conversion/downcast-converters} and
+ * {@link module:engine/conversion/upcast-converters} modules
+ *
+ * Besides allowing to register converters to specific dispatchers, you can also use methods available in this
+ * class to add two-way converters (upcast and downcast):
+ *
+ * * {@link module:engine/conversion/conversion~Conversion#elementToElement `elementToElement()`} –
+ * model element to view element and vice versa
+ * * {@link module:engine/conversion/conversion~Conversion#attributeToElement `attributeToElement()`} –
+ * model attribute to view element and vice versa
+ * * {@link module:engine/conversion/conversion~Conversion#attributeToElement `attributeToElement()`} –
+ * model attribute to view element and vice versa
  */
 export default class Conversion {
 	/**

+ 15 - 4
packages/ckeditor5-engine/src/view/element.js

@@ -18,11 +18,22 @@ import Matcher from './matcher';
 /**
  * View element.
  *
- * Editing engine does not define fixed HTML DTD. This is why the type of the {@link module:engine/view/element~Element} need to
- * be defined by the feature developer. Creating an element you should use {@link module:engine/view/containerelement~ContainerElement}
- * class, {@link module:engine/view/attributeelement~AttributeElement} class or {@link module:engine/view/emptyelement~EmptyElement} class.
+ * The editing engine does not define a fixed semantics of its elements (it is "DTD-free").
+ * This is why the type of the {@link module:engine/view/element~Element} need to
+ * be defined by the feature developer. When creating an element you should use one of the following methods:
  *
- * Note that for view elements which are not created from model, like elements from mutations, paste or
+ * * {@link module:engine/view/writer~Writer#createContainerElement `writer.createContainerElement()`} in order to create
+ * a {@link module:engine/view/containerelement~ContainerElement},
+ * * {@link module:engine/view/writer~Writer#createAttributeElement `writer.createAttributeElement()`} in order to create
+ * a {@link module:engine/view/attributeelement~AttributeElement},
+ * * {@link module:engine/view/writer~Writer#createEmptyElement `writer.createEmptyElement()`} in order to create
+ * a {@link module:engine/view/emptyelement~EmptyElement}.
+ * * {@link module:engine/view/writer~Writer#createUIElement `writer.createUIElement()`} in order to create
+ * a {@link module:engine/view/uielement~UIElement}.
+ * * {@link module:engine/view/writer~Writer#createEditableElement `writer.createEditableElement()`} in order to create
+ * a {@link module:engine/view/editableelement~EditableElement}.
+ *
+ * Note that for view elements which are not created from the model, like elements from mutations, paste or
  * {@link module:engine/controller/datacontroller~DataController#set data.set} it is not possible to define the type of the element, so
  * these will be instances of the {@link module:engine/view/element~Element}.
  *