Ver Fonte

Docs: Fixed docs.

Szymon Cofalik há 8 anos atrás
pai
commit
c5256e1ede

+ 9 - 9
packages/ckeditor5-engine/src/conversion/conversion.js

@@ -63,24 +63,24 @@ export default class Conversion {
 	 *
 	 * For downcast (model to view conversion), these are:
 	 *
-	 * * {@link module:engine/conversion/downcast-helpers~elementToElement model element to view element conversion helper},
-	 * * {@link module:engine/conversion/downcast-helpers~attributeToElement model attribute to view element conversion helper},
-	 * * {@link module:engine/conversion/downcast-helpers~attributeToAttribute model attribute to view attribute conversion helper}.
+	 * * {@link module:engine/conversion/downcast-helpers~downcastElementToElement downcast element to element helper},
+	 * * {@link module:engine/conversion/downcast-helpers~downcastAttributeToElement downcast attribute to element helper},
+	 * * {@link module:engine/conversion/downcast-helpers~downcastAttributeToAttribute downcast attribute to attribute helper}.
 	 *
 	 * For upcast (view to model conversion), these are:
 	 *
-	 * * {view element to model element conversion helper,
-	 * * view element to model attribute conversion helper,
-	 * * view attribute to model attribute conversion helper.
+	 * * {@link module:engine/conversion/upcast-helpers~upcastElementToElement upcast element to element helper},
+	 * * {@link module:engine/conversion/upcast-helpers~upcastElementToAttribute upcast attribute to element helper},
+	 * * {@link module:engine/conversion/upcast-helpers~upcastAttributeToAttribute upcast attribute to attribute helper}.
 	 *
-	 * An example of using model conversion helpers to convert `paragraph` model element to `p` view element (and back):
+	 * An example of using conversion helpers to convert `paragraph` model element to `p` view element (and back):
 	 *
 	 *		// Define conversion configuration - model element 'paragraph' should be converted to view element 'p'.
 	 *		const config = { model: 'paragraph', view: 'p' };
 	 *
 	 *		// Add converters to proper dispatchers using conversion helpers.
-	 *		conversion.for( 'downcast' ).add( modelElementToElement( config ) );
-	 *		conversion.for( 'upcast' ).add( viewElementToElement( config ) );
+	 *		conversion.for( 'downcast' ).add( downcastElementToElement( config ) );
+	 *		conversion.for( 'upcast' ).add( upcastElementToElement( config ) );
 	 *
 	 * An example of providing custom conversion helper that uses custom converter function:
 	 *

+ 4 - 4
packages/ckeditor5-engine/src/conversion/downcast-helpers.js

@@ -46,7 +46,7 @@ import cloneDeep from '@ckeditor/ckeditor5-utils/src/lib/lodash/cloneDeep';
  *
  * @param {Object} config Conversion configuration.
  * @param {String} config.model Name of the model element to convert.
- * @param {String|module:engine/view/viewelementdefinition~ViewElementDefinition|Function|
+ * @param {String|module:engine/view/elementdefinition~elementDefinition|Function|
  * module:engine/view/containerelement~ContainerElement} config.view View element name, or a view element definition,
  * or a function that takes model element as a parameter and returns a view container element,
  * or a view container element instance. The view element will be used then in conversion.
@@ -121,7 +121,7 @@ export function downcastElementToElement( config, priority = 'normal' ) {
  * @param {Object|Array.<Object>} config Conversion configuration. It is possible to provide multiple configurations in an array.
  * @param {*} [config.model] The value of the converted model attribute for which the `view` property is defined.
  * If omitted, the configuration item will be used as a "default" configuration when no other item matches the attribute value.
- * @param {String|module:engine/view/viewelementdefinition~ViewElementDefinition|Function|
+ * @param {String|module:engine/view/elementdefinition~elementDefinition|Function|
  * module:engine/view/attributeelement~AttributeElement} config.view View element name, or a view element definition,
  * or a function that takes model element as a parameter and returns a view attribute element, or a view attribute element instance.
  * The view element will be used then in conversion.
@@ -260,7 +260,7 @@ export function downcastAttributeToAttribute( modelAttributeKey, config = {}, pr
  *
  * @param {Object} config Conversion configuration.
  * @param {String} config.model Name of the model marker (or model marker group) to convert.
- * @param {module:engine/view/viewelementdefinition~ViewElementDefinition|Function} config.view View element definition
+ * @param {module:engine/view/elementdefinition~elementDefinition|Function} config.view View element definition
  * which will be used to build a view element for conversion or a function that takes model marker data as a parameter and
  * returns view element to use in conversion.
  * @param {module:utils/priorities~PriorityString} [priority='normal'] Converter priority.
@@ -364,7 +364,7 @@ function _normalizeToElementConfig( config, ViewElementClass ) {
 
 // Creates view element instance from provided viewElementDefinition and class.
 //
-// @param {module:engine/view/viewelementdefinition~ViewElementDefinition} viewElementDefinition
+// @param {module:engine/view/elementdefinition~elementDefinition} viewElementDefinition
 // @param {Function} ViewElementClass
 // @returns {module:engine/view/element~Element}
 function _createViewElementFromDefinition( viewElementDefinition, ViewElementClass ) {

+ 1 - 1
packages/ckeditor5-engine/src/conversion/upcast-helpers.js

@@ -240,7 +240,7 @@ export function upcastAttributeToAttribute( config, priority = 'low' ) {
  * 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/document~Document#markers model document markers}.
+ * {@link module:engine/model/model~Model#markers model document markers}.
  *
  *		upcastElementToMarker( { view: 'marker-search', model: 'search' } );
  *

+ 14 - 5
packages/ckeditor5-engine/src/model/markercollection.js

@@ -270,11 +270,20 @@ mix( MarkerCollection, EmitterMixin );
  * Since markers need to track change in the document, for efficiency reasons, it is best to create and keep as little
  * markers as possible and remove them as soon as they are not needed anymore.
  *
- * Markers can be converted to view by adding appropriate converters for
- * {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:addMarker} and
- * {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:removeMarker}
- * events, or by building converters for {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher}
- * using {@link module:engine/conversion/buildmodelconverter~buildModelConverter model converter builder}.
+ * Markers can be downcasted and upcasted.
+ *
+ * Markers downcast happens on {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:addMarker} and
+ * {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:removeMarker} events.
+ * Use {@link module:engine/conversion/downcast-helpers downcast helpers} or attach a custom converter to mentioned events.
+ * For {@link module:engine/controller/datacontroller~DataController data pipeline}, marker should be downcasted to an element.
+ * Then, it can be upcasted back to a marker. Again, use {@link module:engine/conversion/upcast-helpers upcast helpers} or
+ * attach a custom converter to {@link module:engine/conversion/upcastdispatcher~UpcastDispatcher#event:element}.
+ *
+ * Another upside of markers is that finding marked part of document is fast and easy. Using attributes to mark some nodes
+ * and then trying to find that part of document would require traversing whole document tree. Marker gives instant access
+ * to the range which it is marking at the moment.
+ *
+ * `Marker` instances are created and destroyed only by {@link ~MarkerCollection MarkerCollection}.
  */
 class Marker {
 	/**

+ 1 - 1
packages/ckeditor5-engine/src/view/matcher.js

@@ -38,7 +38,7 @@ export default class Matcher {
 	 *			class: 'foobar'
 	 *		} );
 	 *
-	 * See {@link ~MatcherPattern} for more examples.
+	 * See {@link module:engine/view/matcher~MatcherPattern} for more examples.
 	 *
 	 * Multiple patterns can be added in one call:
 	 *