Преглед на файлове

Docs: Rewriting API docs...

Piotrek Koszuliński преди 7 години
родител
ревизия
8b108552fd
променени са 3 файла, в които са добавени 63 реда и са изтрити 37 реда
  1. 24 10
      packages/ckeditor5-engine/src/model/model.js
  2. 36 27
      packages/ckeditor5-engine/src/model/selection.js
  3. 3 0
      packages/ckeditor5-engine/src/model/writer.js

+ 24 - 10
packages/ckeditor5-engine/src/model/model.js

@@ -207,10 +207,15 @@ export default class Model {
 	}
 
 	/**
-	 * {@link module:utils/observablemixin~ObservableMixin#decorate Decorated} function to apply
-	 * {@link module:engine/model/operation/operation~Operation operations} on the model.
+	 * {@link module:utils/observablemixin~ObservableMixin#decorate Decorated} function for applying
+	 * {@link module:engine/model/operation/operation~Operation operations} to the model.
 	 *
-	 * @param {module:engine/model/operation/operation~Operation} operation Operation to apply
+	 * This is a low-level way of changing the model. It is exposed for very specific use cases (like the undo feature).
+	 * Normally, to modify the model, you will want to use {@link module:engine/model/writer~Writer `Writer`}.
+	 * See also {@glink framework/guides/architecture/editing-engine#changing-the-model Changing the model} section
+	 * of the {@glink framework/guides/architecture/editing-engine Editing architecture} guide.
+	 *
+	 * @param {module:engine/model/operation/operation~Operation} operation The operation to apply.
 	 */
 	applyOperation( operation ) {
 		operation._execute();
@@ -320,10 +325,10 @@ export default class Model {
 	 * @param {Object} [options]
 	 * @param {Boolean} [options.leaveUnmerged=false] Whether to merge elements after removing the content of the selection.
 	 *
-	 * For example `<heading>x[x</heading><paragraph>y]y</paragraph>` will become:
+	 * For example `<heading1>x[x</heading1><paragraph>y]y</paragraph>` will become:
 	 *
-	 * * `<heading>x^y</heading>` with the option disabled (`leaveUnmerged == false`)
-	 * * `<heading>x^</heading><paragraph>y</paragraph>` with enabled (`leaveUnmerged == true`).
+	 * * `<heading1>x^y</heading1>` with the option disabled (`leaveUnmerged == false`)
+	 * * `<heading1>x^</heading1><paragraph>y</paragraph>` with enabled (`leaveUnmerged == true`).
 	 *
 	 * Note: {@link module:engine/model/schema~Schema#isObject object} and {@link module:engine/model/schema~Schema#isLimit limit}
 	 * elements will not be merged.
@@ -331,10 +336,10 @@ export default class Model {
 	 * @param {Boolean} [options.doNotResetEntireContent=false] Whether to skip replacing the entire content with a
 	 * paragraph when the entire content was selected.
 	 *
-	 * For example `<heading>[x</heading><paragraph>y]</paragraph>` will become:
+	 * For example `<heading1>[x</heading1><paragraph>y]</paragraph>` will become:
 	 *
 	 * * `<paragraph>^</paragraph>` with the option disabled (`doNotResetEntireContent == false`)
-	 * * `<heading>^</heading>` with enabled (`doNotResetEntireContent == true`)
+	 * * `<heading1>^</heading1>` with enabled (`doNotResetEntireContent == true`)
 	 */
 	deleteContent( selection, options ) {
 		deleteContent( this, selection, options );
@@ -379,13 +384,22 @@ export default class Model {
 	 * For example, for the following selection:
 	 *
 	 * ```html
-	 * <p>x</p><quote><p>y</p><h>fir[st</h></quote><p>se]cond</p><p>z</p>
+	 * <paragraph>x</paragraph>
+	 * <blockQuote>
+	 *	<paragraph>y</paragraph>
+	 *	<heading1>fir[st</heading1>
+	 * </blockQuote>
+	 * <paragraph>se]cond</paragraph>
+	 * <paragraph>z</paragraph>
 	 * ```
 	 *
 	 * It will return a document fragment with such a content:
 	 *
 	 * ```html
-	 * <quote><h>st</h></quote><p>se</p>
+	 * <blockQuote>
+	 *	<heading1>st</heading1>
+	 * </blockQuote>
+	 * <paragraph>se</paragraph>
 	 * ```
 	 *
 	 * @fires getSelectedContent

+ 36 - 27
packages/ckeditor5-engine/src/model/selection.js

@@ -17,19 +17,23 @@ import mix from '@ckeditor/ckeditor5-utils/src/mix';
 import isIterable from '@ckeditor/ckeditor5-utils/src/isiterable';
 
 /**
- * `Selection` is a group of {@link module:engine/model/range~Range ranges} which has a direction specified by
- * {@link module:engine/model/selection~Selection#anchor anchor} and {@link module:engine/model/selection~Selection#focus focus}.
- * Additionally, `Selection` may have it's own attributes.
+ * Selection is a set of {@link module:engine/model/range~Range ranges}. It has a direction specified by its
+ * {@link module:engine/model/selection~Selection#anchor anchor} and {@link module:engine/model/selection~Selection#focus focus}
+ * (it can be {@link module:engine/model/selection~Selection#isBackward forward or backward}).
+ * Additionally, selection may have its own attributes (think – whether text typed in in this selection
+ * should have those attributes – e.g. whether you type a bolded text).
  *
  * @mixes {module:utils/emittermixin~EmitterMixin}
  */
 export default class Selection {
 	/**
-	 * Creates new selection instance on the given
-	 * {@link module:engine/model/selection~Selection selection}, {@link module:engine/model/position~Position position},
-	 * {@link module:engine/model/element~Element element}, {@link module:engine/model/position~Position position},
-	 * {@link module:engine/model/range~Range range}, an iterable of {@link module:engine/model/range~Range ranges}
-	 * or creates an empty selection if no arguments passed.
+	 * Creates a new selection instance
+	 * based on the given {@link module:engine/model/selection~Selection selection},
+	 * or based on the given {@link module:engine/model/range~Range range},
+	 * or based on an iterable collection of {@link module:engine/model/range~Range ranges}
+	 * or at the given {@link module:engine/model/position~Position position},
+	 * or on the given {@link module:engine/model/element~Element element},
+	 * or creates an empty selection if no arguments were passed.
 	 *
 	 * 		// Creates empty selection without ranges.
 	 *		const selection = new Selection();
@@ -68,7 +72,7 @@ export default class Selection {
 	 * 		// just after the item.
 	 *		const selection = new Selection( paragraph, 'on' );
 	 *
-	 * `Selection`'s constructor allow passing additional options (`backward`) as the last argument.
+	 * Selection's constructor allow passing additional options (`'backward'`) as the last argument.
 	 *
 	 * 		// Creates backward selection.
 	 *		const selection = new Selection( range, { backward: true } );
@@ -111,12 +115,17 @@ export default class Selection {
 	}
 
 	/**
-	 * Selection anchor. Anchor may be described as a position where the most recent part of the selection starts.
-	 * Together with {@link #focus} they define the direction of selection, which is important
-	 * when expanding/shrinking selection. Anchor is always {@link module:engine/model/range~Range#start start} or
-	 * {@link module:engine/model/range~Range#end end} position of the most recently added range.
+	 * Selection anchor. Anchor is the position from which the selection was started. If a user is making a selection
+	 * by dragging the mouse, the anchor is where the user pressed the mouse button (the beggining of the selection).
+	 *
+	 * Anchor and {@link #focus} define the direction of the selection, which is important
+	 * when expanding/shrinking selection. The focus moves, while the anchor should remain in the same place.
+	 *
+	 * Anchor is always set to the {@link module:engine/model/range~Range#start start} or
+	 * {@link module:engine/model/range~Range#end end} position of the last of selection's ranges. Whether it is
+	 * the `start` or `end` depends on the specified `options.backward`. See the {@link #setTo `setTo()`} method.
 	 *
-	 * Is set to `null` if there are no ranges in selection.
+	 * May be set to `null` if there are no ranges in the selection.
 	 *
 	 * @see #focus
 	 * @readonly
@@ -133,9 +142,10 @@ export default class Selection {
 	}
 
 	/**
-	 * Selection focus. Focus is a position where the selection ends.
+	 * Selection focus. Focus is the position where the selection ends. If a user is making a selection
+	 * by dragging the mouse, the focus is where the mouse cursor is.
 	 *
-	 * Is set to `null` if there are no ranges in selection.
+	 * May be set to `null` if there are no ranges in the selection.
 	 *
 	 * @see #anchor
 	 * @readonly
@@ -152,8 +162,8 @@ export default class Selection {
 	}
 
 	/**
-	 * Returns whether the selection is collapsed. Selection is collapsed when there is exactly one range which is
-	 * collapsed.
+	 * Whether the selection is collapsed. Selection is collapsed when there is exactly one range in it
+	 * and it is collapsed.
 	 *
 	 * @readonly
 	 * @type {Boolean}
@@ -169,7 +179,7 @@ export default class Selection {
 	}
 
 	/**
-	 * Returns number of ranges in selection.
+	 * Returns the number of ranges in the selection.
 	 *
 	 * @readonly
 	 * @type {Number}
@@ -179,8 +189,7 @@ export default class Selection {
 	}
 
 	/**
-	 * Specifies whether the {@link #focus}
-	 * precedes {@link #anchor}.
+	 * Specifies whether the selection's {@link #focus} precedes the selection's {@link #anchor}.
 	 *
 	 * @readonly
 	 * @type {Boolean}
@@ -190,8 +199,8 @@ export default class Selection {
 	}
 
 	/**
-	 * Checks whether this selection is equal to given selection. Selections are equal if they have same directions,
-	 * same number of ranges and all ranges from one selection equal to a range from other selection.
+	 * Checks whether this selection is equal to the given selection. Selections are equal if they have the same directions,
+	 * the same number of ranges and all ranges from one selection equal to ranges from the another selection.
 	 *
 	 * @param {module:engine/model/selection~Selection|module:engine/model/documentselection~DocumentSelection} otherSelection
 	 * Selection to compare with.
@@ -227,7 +236,7 @@ export default class Selection {
 	}
 
 	/**
-	 * Returns an iterable that iterates over copies of selection ranges.
+	 * Returns an iterable object that iterates over copies of selection ranges.
 	 *
 	 * @returns {Iterable.<module:engine/model/range~Range>}
 	 */
@@ -703,14 +712,14 @@ export default class Selection {
 		for ( let i = 0; i < this._ranges.length; i++ ) {
 			if ( range.isIntersecting( this._ranges[ i ] ) ) {
 				/**
-				 * Trying to add a range that intersects with another range from selection.
+				 * Trying to add a range that intersects with another range in the selection.
 				 *
 				 * @error model-selection-range-intersects
 				 * @param {module:engine/model/range~Range} addedRange Range that was added to the selection.
-				 * @param {module:engine/model/range~Range} intersectingRange Range from selection that intersects with `addedRange`.
+				 * @param {module:engine/model/range~Range} intersectingRange Range in the selection that intersects with `addedRange`.
 				 */
 				throw new CKEditorError(
-					'model-selection-range-intersects: Trying to add a range that intersects with another range from selection.',
+					'model-selection-range-intersects: Trying to add a range that intersects with another range in the selection.',
 					{ addedRange: range, intersectingRange: this._ranges[ i ] }
 				);
 			}

+ 3 - 0
packages/ckeditor5-engine/src/model/writer.js

@@ -145,6 +145,9 @@ export default class Writer {
 	 * If you want to move {@link module:engine/model/range~Range range} instead of an
 	 * {@link module:engine/model/item~Item item} use {@link module:engine/model/writer~Writer#move `Writer#move()`}.
 	 *
+	 * **Note:** For a paste-like content insertion mechanism see
+	 * {@link module:engine/model/model~Model#insertContent `model.insertContent()`}.
+	 *
 	 * @param {module:engine/model/item~Item|module:engine/model/documentfragment~DocumentFragment} item Item or document
 	 * fragment to insert.
 	 * @param {module:engine/model/item~Item|module:engine/model/position~Position} itemOrPosition