Procházet zdrojové kódy

Docs: Fixes in docs.

Szymon Cofalik před 8 roky
rodič
revize
7e70542bd8

+ 49 - 22
packages/ckeditor5-engine/src/conversion/modelconversiondispatcher.js

@@ -31,27 +31,38 @@ import extend from '@ckeditor/ckeditor5-utils/src/lib/lodash/extend';
  * To map positions and elements during model to view conversion use {@link module:engine/conversion/mapper~Mapper}.
  *
  * `ModelConversionDispatcher` fires following events for model tree changes:
- * * {@link #event:insert insert} if a range of nodes has been inserted to the model tree,
- * * {@link #event:remove remove} if a range of nodes has been removed from the model tree,
- * * {@link #event:attribute attribute} if attribute has been added, changed or removed from a model node.
  *
- * For {@link #event:insert insert} and {@link #event:attribute attribute}, `ModelConversionDispatcher` generates
- * {@link module:engine/conversion/modelconsumable~ModelConsumable consumables}. These are used to have a control
- * over which changes has been already consumed. It is useful when some converters overwrite other or converts multiple
- * changes (for example converts insertion of an element and also converts that element's attributes during insertion).
+ * * {@link module:engine/conversion/modelconversiondispatcher~ModelConversionDispatcher#event:insert insert}
+ * if a range of nodes has been inserted to the model tree,
+ * * {@link module:engine/conversion/modelconversiondispatcher~ModelConversionDispatcher#event:remove remove}
+ * if a range of nodes has been removed from the model tree,
+ * * {@link module:engine/conversion/modelconversiondispatcher~ModelConversionDispatcher#event:attribute attribute}
+ * if attribute has been added, changed or removed from a model node.
  *
- * Additionally, `ModelConversionDispatcher` fires events for {@link module:engine/model/markerscollection~Marker marker} changes:
- * * {@link #event:addMarker} if a marker has been added,
- * * {@link #event:removeMarker} if a marker has been removed.
+ * For {@link module:engine/conversion/modelconversiondispatcher~ModelConversionDispatcher#event:insert insert}
+ * and {@link module:engine/conversion/modelconversiondispatcher~ModelConversionDispatcher#event:attribute attribute},
+ * `ModelConversionDispatcher` generates {@link module:engine/conversion/modelconsumable~ModelConsumable consumables}.
+ * These are used to have a control over which changes has been already consumed. It is useful when some converters
+ * overwrite other or converts multiple changes (for example converts insertion of an element and also converts that
+ * element's attributes during insertion).
+ *
+ * Additionally, `ModelConversionDispatcher` fires events for {@link module:engine/model/markercollection~Marker marker} changes:
+ *
+ * * {@link module:engine/conversion/modelconversiondispatcher~ModelConversionDispatcher#event:addMarker} if a marker has been added,
+ * * {@link module:engine/conversion/modelconversiondispatcher~ModelConversionDispatcher#event:removeMarker} if a marker has been removed.
  *
  * Note, that changing a marker is done through removing the marker from the old range, and adding on the new range,
  * so both those events are fired.
  *
  * Finally, `ModelConversionDispatcher` also handles firing events for {@link module:engine/model/selection model selection}
  * conversion:
- * * {@link #event:selection} which converts selection from model to view,
- * * {@link #event:selectionAttribute} which is fired for every selection attribute,
- * * {@link #event:selectionMarker} which is fired for every marker which contains selection.
+ *
+ * * {@link module:engine/conversion/modelconversiondispatcher~ModelConversionDispatcher#event:selection}
+ * which converts selection from model to view,
+ * * {@link module:engine/conversion/modelconversiondispatcher~ModelConversionDispatcher#event:selectionAttribute}
+ * which is fired for every selection attribute,
+ * * {@link module:engine/conversion/modelconversiondispatcher~ModelConversionDispatcher#event:selectionMarker}
+ * which is fired for every marker which contains selection.
  *
  * Unlike model tree and markers, events for selection are not fired for changes but for selection state.
  *
@@ -426,7 +437,7 @@ export default class ModelConversionDispatcher {
 	 * Fired for inserted nodes.
 	 *
 	 * `insert` is a namespace for a class of events. Names of actually called events follow this pattern:
-	 * `insert:<name>`. `name` is either `'$text'`, when {@link module:engine/model/text~Text a text node} has been inserted,
+	 * `insert:name`. `name` is either `'$text'`, when {@link module:engine/model/text~Text a text node} has been inserted,
 	 * or {@link module:engine/model/element~Element#name name} of inserted element.
 	 *
 	 * This way listeners can either listen to a general `insert` event or specific event (for example `insert:paragraph`).
@@ -443,7 +454,7 @@ export default class ModelConversionDispatcher {
 	 * Fired for removed nodes.
 	 *
 	 * `remove` is a namespace for a class of events. Names of actually called events follow this pattern:
-	 * `remove:<name>`. `name` is either `'$text'`, when {@link module:engine/model/text~Text a text node} has been removed,
+	 * `remove:name`. `name` is either `'$text'`, when {@link module:engine/model/text~Text a text node} has been removed,
 	 * or the {@link module:engine/model/element~Element#name name} of removed element.
 	 *
 	 * This way listeners can either listen to a general `remove` event or specific event (for example `remove:paragraph`).
@@ -460,7 +471,7 @@ export default class ModelConversionDispatcher {
 	 * Fired when attribute has been added/changed/removed from a node.
 	 *
 	 * `attribute` is a namespace for a class of events. Names of actually called events follow this pattern:
-	 * `attribute:<attributeKey>:<name>`. `attributeKey` is the key of added/changed/removed attribute.
+	 * `attribute:attributeKey:name`. `attributeKey` is the key of added/changed/removed attribute.
 	 * `name` is either `'$text'` if change was on {@link module:engine/model/text~Text a text node},
 	 * or the {@link module:engine/model/element~Element#name name} of element which attribute has changed.
 	 *
@@ -490,7 +501,7 @@ export default class ModelConversionDispatcher {
 	 * Fired for {@link module:engine/model/selection~Selection selection} attributes changes.
 	 *
 	 * `selectionAttribute` is a namespace for a class of events. Names of actually called events follow this pattern:
-	 * `selectionAttribute:<attributeKey>`. `attributeKey` is the key of selection attribute. This way listen can listen to
+	 * `selectionAttribute:attributeKey`. `attributeKey` is the key of selection attribute. This way it is possible to listen to
 	 * certain attribute, i.e. `selectionAttribute:bold`.
 	 *
 	 * @event selectionAttribute
@@ -503,10 +514,25 @@ export default class ModelConversionDispatcher {
 	 */
 
 	/**
+	 * Fired for markers containing {@link module:engine/model/selection~Selection selection}.
+	 *
+	 * `selectionMarker` is a namespace for a class of events. Names of actually called events follow this pattern:
+	 * `selectionMarker:markerName`. `markerName` is the name of the marker containing selection. This way it is possible to listen to
+	 * certain marker, i.e. `selectionAttribute:highlight`.
+	 *
+	 * @event selectionMarker
+	 * @param {Object} data Additional information about the change.
+	 * @param {module:engine/model/selection~Selection} data.selection Selection that is converted.
+	 * @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 `ModelConversionDispatcher` constructor.
+	 */
+
+	/**
 	 * Fired when a new marker is added to the model.
 	 *
 	 * `addMarker` is a namespace for a class of events. Names of actually called events follow this pattern:
-	 * `addMarker:<markerName>`. By specifying certain marker names, you can make the events even more gradual. For example,
+	 * `addMarker:markerName`. By specifying certain marker names, you can make the events even more gradual. For example,
 	 * if markers are named `foo:abc`, `foo:bar`, then it is possible to listen to `addMarker:foo` or `addMarker:foo:abc` and
 	 * `addMarker:foo:bar` events.
 	 *
@@ -521,8 +547,9 @@ export default class ModelConversionDispatcher {
 	 * @event addMarker
 	 * @param {Object} data Additional information about the change.
 	 * @param {module:engine/model/item~Item} data.item Item inside the new marker.
-	 * @param {module:engine/model/range~Range} data.range Range spanning over converted item.
-	 * @param {module:engine/model/range~Range} data.range Marker range.
+	 * @param {module:engine/model/range~Range} [data.range] Range spanning over converted item. Available only if
+	 * the marker range was not collapsed.
+	 * @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 `ModelConversionDispatcher` constructor.
@@ -532,13 +559,13 @@ export default class ModelConversionDispatcher {
 	 * Fired when marker is removed from the model.
 	 *
 	 * `removeMarker` is a namespace for a class of events. Names of actually called events follow this pattern:
-	 * `removeMarker:<markerName>`. By specifying certain marker names, you can make the events even more gradual. For example,
+	 * `removeMarker:markerName`. By specifying certain marker names, you can make the events even more gradual. For example,
 	 * if markers are named `foo:abc`, `foo:bar`, then it is possible to listen to `removeMarker:foo` or `removeMarker:foo:abc` and
 	 * `removeMarker:foo:bar` events.
 	 *
 	 * @event removeMarker
 	 * @param {Object} data Additional information about the change.
-	 * @param {module:engine/model/range~Range} data.range Marker range.
+	 * @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 `ModelConversionDispatcher` constructor.
 	 */