浏览代码

Improved docs.

Oskar Wróbel 8 年之前
父节点
当前提交
71cb2e6e6a

+ 8 - 14
packages/ckeditor5-engine/src/controller/datacontroller.js

@@ -180,10 +180,7 @@ export default class DataController {
 
 	/**
 	 * Sets input data parsed by the {@link #processor data processor} and
-	 * converted by the {@link #viewToModel view to model converters}. If markers where converted
-	 * from view to model as temporary {@link module:engine/model/element/~Element model elements} then those elements
-	 * will be removed from parsed {@link module:engine/model/element/~DocumentFragment} and added to the
-	 * {@link module:engine/model/document~Document#markers markers collection}.
+	 * converted by the {@link #viewToModel view to model converters}.
 	 *
 	 * This method also creates a batch with all the changes applied. If all you need is to parse data use
 	 * the {@link #parse} method.
@@ -234,7 +231,7 @@ export default class DataController {
 	 * @param {String} data Data to parse.
 	 * @param {String} [context='$root'] Base context in which the view will be converted to the model. See:
 	 * {@link module:engine/conversion/viewconversiondispatcher~ViewConversionDispatcher#convert}.
-	 * @returns {ParsedModel} Result of parsing view to model.
+	 * @returns {engine/controller/datacontroller~ParsedModelData} Result of parsing view to model.
 	 */
 	parse( data, context = '$root' ) {
 		// data -> view
@@ -245,16 +242,15 @@ export default class DataController {
 	}
 
 	/**
-	 * Returns the content of the given {@link module:engine/view/element~Element view element} or
+	 * Returns result of the given {@link module:engine/view/element~Element view element} or
 	 * {@link module:engine/view/documentfragment~DocumentFragment view document fragment} converted by the
-	 * {@link #viewToModel view to model converters} to a
-	 * {@link module:engine/model/documentfragment~DocumentFragment model document fragment}.
+	 * {@link #viewToModel view to model converters}.
 	 *
 	 * @param {module:engine/view/element~Element|module:engine/view/documentfragment~DocumentFragment} viewElementOrFragment
 	 * Element or document fragment which content will be converted.
 	 * @param {String} [context='$root'] Base context in which the view will be converted to the model. See:
 	 * {@link module:engine/conversion/viewconversiondispatcher~ViewConversionDispatcher#convert}.
-	 * @returns {ParsedModel} Result of parsing view to model.
+	 * @returns {engine/controller/datacontroller~ParsedModelData} Result of parsing view to model.
 	 */
 	toModel( viewElementOrFragment, context = '$root' ) {
 		const conversionData = this.viewToModel.convert( viewElementOrFragment, { context: [ context ] } );
@@ -273,10 +269,6 @@ export default class DataController {
 	/**
 	 * See {@link module:engine/controller/insertcontent~insertContent}.
 	 *
-	 * Note that data inserted by a data pipeline might contain temporary {@link module:engine/model/element/~Element elements}
-	 * marking {@link module:engine/model/document~Document#markers markers} ranges. We need to remove them because
-	 * data pipeline allows to set markers only by a {@link #set set method}.
-	 *
 	 * @fires insertContent
 	 * @param {module:engine/model/documentfragment~DocumentFragment} content The content to insert.
 	 * @param {module:engine/model/selection~Selection} selection Selection into which the content should be inserted.
@@ -337,7 +329,9 @@ export default class DataController {
 mix( DataController, EmitterMixin );
 
 /**
- * @typedef {Object} ParsedModel Result of parsing view to model.
+ * Result of parsing view to model.
+ *
+ * @typedef {Object} {engine/controller/datacontroller~ParsedModelData}
  * @property {module:engine/model/documentfragment~DocumentFragment|module:engine/model/node~Node} modelItem
  * Fragment of parsed model.
  * @property {Map} markersData List of parsed marker stamps in format [ 'markerName', { startPath: [ 1, 1 ], endPath: [ 1, 3 ] } ]

+ 10 - 16
packages/ckeditor5-engine/src/conversion/viewconversiondispatcher.js

@@ -134,25 +134,20 @@ export default class ViewConversionDispatcher {
 	 * viewItem Part of the view to be converted.
 	 * @param {Object} [additionalData] Additional data to be passed in `data` argument when firing `ViewConversionDispatcher`
 	 * events. See also {@link ~ViewConversionDispatcher#event:element element event}.
-	 * @returns {module:engine/model/documentfragment~DocumentFragment} Model document fragment that is a result of the conversion process.
+	 * @returns {engine/conversion/viewconversiondispatcher~ConvertedModelData} Model data that is a result of the conversion process.
 	 */
 	convert( viewItem, additionalData = {} ) {
 		this.fire( 'viewCleanup', viewItem );
 
 		const consumable = ViewConsumable.createFrom( viewItem );
-
 		const conversionResult = this._convertItem( viewItem, consumable, additionalData );
+		let markersData = new Map();
 
 		if ( conversionResult instanceof ModelNode || conversionResult instanceof ModelDocumentFragment ) {
-			const { modelItem, markersData } = extractMarkersFromModelFragment( conversionResult );
-
-			return {
-				conversionResult: modelItem,
-				markersData: markersData
-			};
+			markersData = extractMarkersFromModelFragment( conversionResult );
 		}
 
-		return { conversionResult, markersData: new Map() };
+		return { conversionResult, markersData };
 	}
 
 	/**
@@ -242,13 +237,13 @@ mix( ViewConversionDispatcher, EmitterMixin );
 // DocumentFragment but path of this element is stored in a Map which is then returned.
 //
 // @param {module:engine/view/documentfragment~DocumentFragment|module:engine/view/node~Node} modelItem Fragment of model.
-// @returns {Object} Object with cleaned up model fragment and Map with markers data.
+// @returns {Map} List of markers data in format [ 'markerName', { startPath: [ 1, 1 ], endPath: [ 1, 4 ] } ].
 function extractMarkersFromModelFragment( modelItem ) {
 	const markerStamps = new Set();
 	const markersData = new Map();
 
 	if ( modelItem.is( 'text' ) ) {
-		return { modelItem, markersData };
+		return markersData;
 	}
 
 	// Create ModelTreeWalker.
@@ -283,16 +278,15 @@ function extractMarkersFromModelFragment( modelItem ) {
 		remove( ModelRange.createOn( stamp ) );
 	}
 
-	return { modelItem, markersData };
+	return markersData;
 }
 
 /**
  * Model data that is a result of the conversion process.
  *
- * @typedef {Object} engine/conversion/viewconversiondispatcher~ConvertedModelDocument
- * @property {module:engine/model/documentfragment~DocumentFragment|module:engine/model/element~Element|
- * module:engine/model/text~Text} modelItem Model document item.
- * @property {Map} markersData Map with markers data in format [ 'markerName', { startPath: [ 1, 1 ], endPath: [ 1, 4 ] } ]
+ * @typedef {ConvertedModelData} engine/conversion/viewconversiondispatcher~ConvertedModelData
+ * @property {module:engine/model/documentfragment~DocumentFragment|module:engine/model/element~Node} conversionResult Converted model item.
+ * @property {Map<Object>} markersData Map with markers data in format [ 'markerName', { startPath: [ 1, 1 ], endPath: [ 1, 4 ] } ].
  */
 
 /**