Browse Source

Docs: A lot of corrections all across the docs.

Piotrek Koszuliński 7 years ago
parent
commit
6321ebfd65

+ 3 - 12
packages/ckeditor5-engine/src/model/liverange.js

@@ -41,7 +41,7 @@ export default class LiveRange extends Range {
 	}
 
 	/**
-	 * Creates a {@link module:engine/model/range~Range range instance}, which is equal to this live range.
+	 * Creates a {@link module:engine/model/range~Range range instance} that is equal to this live range.
 	 *
 	 * @returns {module:engine/model/range~Range}
 	 */
@@ -50,10 +50,10 @@ export default class LiveRange extends Range {
 	}
 
 	/**
-	 * Creates a `LiveRange` instance that is equal to position.
+	 * Creates a `LiveRange` instance that is equal to the given range.
 	 *
 	 * @param {module:engine/model/range~Range} range
-	 * @returns {module:engine/model/range~Range}
+	 * @returns {module:engine/model/liverange~LiveRange}
 	 */
 	static fromRange( range ) {
 		return new LiveRange( range.start, range.end );
@@ -88,15 +88,6 @@ export default class LiveRange extends Range {
 	 */
 
 	/**
-	 * @see module:engine/model/range~Range._createFromRange
-	 * @static
-	 * @protected
-	 * @method module:engine/model/liverange~LiveRange.fromRange
-	 * @param {module:engine/model/range~Range} range
-	 * @returns {module:engine/model/liverange~LiveRange}
-	 */
-
-	/**
 	 * Fired when `LiveRange` instance boundaries have changed due to changes in the
 	 * {@link module:engine/model/document~Document document}.
 	 *

+ 45 - 44
packages/ckeditor5-engine/src/model/model.js

@@ -446,10 +446,11 @@ export default class Model {
 	}
 
 	/**
-	 * Checks whether given {@link module:engine/model/range~Range range} or {@link module:engine/model/element~Element element}
+	 * Checks whether the given {@link module:engine/model/range~Range range} or
+	 * {@link module:engine/model/element~Element element}
 	 * has any content.
 	 *
-	 * Content is any text node or element which is registered in {@link module:engine/model/schema~Schema schema}.
+	 * Content is any text node or element which is registered in the {@link module:engine/model/schema~Schema schema}.
 	 *
 	 * @param {module:engine/model/range~Range|module:engine/model/element~Element} rangeOrElement Range or element to check.
 	 * @returns {Boolean}
@@ -474,10 +475,10 @@ export default class Model {
 	}
 
 	/**
-	 * Creates a position.
+	 * Creates a position from the given root and path in that root.
 	 *
-	 * **Note:** This method is also available on `writer` instance as
-	 * {@link module:engine/model/writer~Writer#createPositionFromPath writer.createPositionFromPath()}:
+	 * Note: This method is also available as
+	 * {@link module:engine/model/writer~Writer#createPositionFromPath `Writer#createPositionFromPath()`}.
 	 *
 	 * @param {module:engine/model/element~Element|module:engine/model/documentfragment~DocumentFragment} root Root of the position.
 	 * @param {Array.<Number>} path Position path. See {@link module:engine/model/position~Position#path}.
@@ -493,17 +494,18 @@ export default class Model {
 	 * Creates position at the given location. The location can be specified as:
 	 *
 	 * * a {@link module:engine/model/position~Position position},
-	 * * parent element and offset (offset defaults to `0`),
-	 * * parent element and `'end'` (sets position at the end of that element),
-	 * * {@link module:engine/model/item~Item model item} and `'before'` or `'after'` (sets position before or after given model item).
+	 * * a parent element and offset in that element,
+	 * * a parent element and `'end'` (the position will be set at the end of that element),
+	 * * a {@link module:engine/model/item~Item model item} and `'before'` or `'after'`
+	 * (the position will be set before or after the given model item).
 	 *
 	 * This method is a shortcut to other factory methods such as:
 	 *
-	 * * {@link module:engine/model/model~Model#createPositionBefore},
-	 * * {@link module:engine/model/model~Model#createPositionAfter}.
+	 * * {@link module:engine/model/model~Model#createPositionBefore `createPositionBefore()`},
+	 * * {@link module:engine/model/model~Model#createPositionAfter `createPositionAfter()`}.
 	 *
-	 * **Note:** This method is also available on `writer` instance as
-	 * {@link module:engine/model/writer~Writer#createPositionAt writer.createPositionAt()}:
+	 * Note: This method is also available as
+	 * {@link module:engine/model/writer~Writer#createPositionAt `Writer#createPositionAt()`},
 	 *
 	 * @param {module:engine/model/item~Item|module:engine/model/position~Position} itemOrPosition
 	 * @param {Number|'end'|'before'|'after'} [offset] Offset or one of the flags. Used only when
@@ -514,10 +516,10 @@ export default class Model {
 	}
 
 	/**
-	 * Creates a new position, after given {@link module:engine/model/item~Item model item}.
+	 * Creates a new position after the given {@link module:engine/model/item~Item model item}.
 	 *
-	 * **Note:** This method is also available on `writer` instance as
-	 * {@link module:engine/model/writer~Writer#createPositionAfter writer.createPositionAfter()}:
+	 * Note: This method is also available as
+	 * {@link module:engine/model/writer~Writer#createPositionAfter `Writer#createPositionAfter()`}.
 	 *
 	 * @param {module:engine/model/item~Item} item Item after which the position should be placed.
 	 * @returns {module:engine/model/position~Position}
@@ -527,10 +529,10 @@ export default class Model {
 	}
 
 	/**
-	 * Creates a new position, before the given {@link module:engine/model/item~Item model item}.
+	 * Creates a new position before the given {@link module:engine/model/item~Item model item}.
 	 *
-	 * **Note:** This method is also available on `writer` instance as
-	 * {@link module:engine/model/writer~Writer#createPositionBefore writer.createPositionBefore()}:
+	 * Note: This method is also available as
+	 * {@link module:engine/model/writer~Writer#createPositionBefore `Writer#createPositionBefore()`}.
 	 *
 	 * @param {module:engine/model/item~Item} item Item before which the position should be placed.
 	 * @returns {module:engine/model/position~Position}
@@ -540,20 +542,18 @@ export default class Model {
 	}
 
 	/**
-	 * Creates a range spanning from `start` position to `end` position.
+	 * Creates a range spanning from the `start` position to the `end` position.
 	 *
-	 * **Note:** Range constructor creates it's own {@link module:engine/model/position~Position Position} instances
-	 * basing on passed values.
-	 *
-	 * **Note:** This method is also available on `writer` instance as
-	 * {@link module:engine/model/writer~Writer#createRange writer.createRange()}:
+	 * Note: This method is also available as
+	 * {@link module:engine/model/writer~Writer#createRange `Writer#createRange()`}:
 	 *
 	 *		model.change( writer => {
-	 *			const range = writer.createRange( paragraph );
+	 *			const range = writer.createRange( start, end );
 	 *		} );
 	 *
 	 * @param {module:engine/model/position~Position} start Start position.
-	 * @param {module:engine/model/position~Position} [end] End position. If not set, range will be collapsed at `start` position.
+	 * @param {module:engine/model/position~Position} [end] End position. If not set, the range will be collapsed
+	 * to the `start` position.
 	 * @returns {module:engine/model/range~Range}
 	 */
 	createRange( start, end ) {
@@ -561,11 +561,11 @@ export default class Model {
 	}
 
 	/**
-	 * Creates a range inside an {@link module:engine/model/element~Element element} which starts before the first child of
+	 * Creates a range inside the given element which starts before the first child of
 	 * that element and ends after the last child of that element.
 	 *
-	 * **Note:** This method is also available on `writer` instance as
-	 * {@link module:engine/model/writer~Writer#createRangeIn writer.createRangeIn()}:
+	 * Note: This method is also available as
+	 * {@link module:engine/model/writer~Writer#createRangeIn `Writer#createRangeIn()`}:
 	 *
 	 *		model.change( writer => {
 	 *			const range = writer.createRangeIn( paragraph );
@@ -579,10 +579,10 @@ export default class Model {
 	}
 
 	/**
-	 * Creates a range that starts before given {@link module:engine/model/item~Item model item} and ends after it.
+	 * Creates a range that starts before the given {@link module:engine/model/item~Item model item} and ends after it.
 	 *
-	 * **Note:** This method is also available on `writer` instance as
-	 * {@link module:engine/model/writer~Writer#createRangeOn writer.createRangeOn()}:
+	 * Note: This method is also available on `writer` instance as
+	 * {@link module:engine/model/writer~Writer#createRangeOn `Writer.createRangeOn()`}:
 	 *
 	 *		model.change( writer => {
 	 *			const range = writer.createRangeOn( paragraph );
@@ -596,16 +596,17 @@ export default class Model {
 	}
 
 	/**
-	 * 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 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 the given 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.
 	 *
-	 * **Note:** This method is also available on `writer` instance as
-	 * {@link module:engine/model/writer~Writer#createSelection writer.createSelection()}:
+	 * Note: This method is also available as
+	 * {@link module:engine/model/writer~Writer#createSelection `Writer#createSelection()`}.
 	 *
 	 *		// Creates empty selection without ranges.
 	 *		const selection = writer.createSelection();
@@ -644,7 +645,7 @@ export default class Model {
 	 *		// just after the item.
 	 *		const selection = writer.createSelection( paragraph, 'on' );
 	 *
-	 * Selection's constructor allow passing additional options (`'backward'`) as the last argument.
+	 *		// Additional options (`'backward'`) can be specified as the last argument.
 	 *
 	 *		// Creates backward selection.
 	 *		const selection = writer.createSelection( range, { backward: true } );
@@ -666,8 +667,8 @@ export default class Model {
 	 *
 	 * **Note:** In most cases creating a batch instance is not necessary as they are created when using:
 	 *
-	 * * {@link #change},
-	 * * {@link #enqueueChange}.
+	 * * {@link #change `change()`},
+	 * * {@link #enqueueChange `enqueueChange()`}.
 	 *
 	 * @returns {module:engine/model/batch~Batch}
 	 */

+ 18 - 13
packages/ckeditor5-engine/src/model/position.js

@@ -16,20 +16,25 @@ import { last } from 'lodash-es';
 /**
  * Represents a position in the model tree.
  *
- * **Note:** Position is based on offsets, not indexes. This means that position in element containing two text nodes
- * with data `foo` and `bar`, position between them has offset `3`, not `1`.
- * See {@link module:engine/model/position~Position#path} for more.
+ * A position is represented by its {@link module:engine/model/position~Position#root} and
+ * a {@link module:engine/model/position~Position#path} in that root.
  *
- * Since position in a model is represented by a {@link module:engine/model/position~Position#root position root} and
- * {@link module:engine/model/position~Position#path position path} it is possible to create positions placed in non-existing elements.
- * This requirement is important for operational transformation.
+ * You can create position instances via its constructor or the `createPosition*()` factory methods of
+ * {@link module:engine/model/model~Model} and {@link module:engine/model/writer~Writer}.
+ *
+ * **Note:** Position is based on offsets, not indexes. This means that a position between two text nodes
+ * `foo` and `bar` has offset `3`, not `1`. See {@link module:engine/model/position~Position#path} for more information.
+ *
+ * Since a position in the model is represented by a {@link module:engine/model/position~Position#root position root} and
+ * {@link module:engine/model/position~Position#path position path} it is possible to create positions placed in non-existing places.
+ * This requirement is important for operational transformation algorithms.
  *
  * Also, {@link module:engine/model/operation/operation~Operation operations}
- * kept in {@link module:engine/model/document~Document#history document history}
+ * kept in the {@link module:engine/model/document~Document#history document history}
  * are storing positions (and ranges) which were correct when those operations were applied, but may not be correct
- * after document got changed.
+ * after the document has changed.
  *
- * When changes are applied to model, it may also happen that {@link module:engine/model/position~Position#parent position parent}
+ * When changes are applied to the model, it may also happen that {@link module:engine/model/position~Position#parent position parent}
  * will change even if position path has not changed. Keep in mind, that if a position leads to non-existing element,
  * {@link module:engine/model/position~Position#parent} and some other properties and methods will throw errors.
  *
@@ -841,14 +846,14 @@ export default class Position {
 				return this._createAfter( node );
 			} else if ( offset !== 0 && !offset ) {
 				/**
-				 * {@link module:engine/model/position~Position.createAt `Position.createAt()`}
+				 * {@link module:engine/model/model~Model#createPositionAt `Model#createPositionAt()`}
 				 * requires the offset to be specified when the first parameter is a model item.
 				 *
-				 * @error model-position-createAt-offset-required
+				 * @error model-createPositionAt-offset-required
 				 */
 				throw new CKEditorError(
-					'model-position-createAt-offset-required: ' +
-					'Position.createAt() requires the offset when the first parameter is a model item.' );
+					'model-createPositionAt-offset-required: ' +
+					'Model#createPositionAt() requires the offset when the first parameter is a model item.' );
 			}
 
 			if ( !node.is( 'element' ) && !node.is( 'documentFragment' ) ) {

+ 7 - 7
packages/ckeditor5-engine/src/model/range.js

@@ -13,18 +13,18 @@ import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
 import compareArrays from '@ckeditor/ckeditor5-utils/src/comparearrays';
 
 /**
- * Range class. Range is iterable.
+ * Represents a range in the model tree.
+ *
+ * A range is defined by its {@link module:engine/model/range~Range#start} and {@link module:engine/model/range~Range#end}
+ * positions.
+ *
+ * You can create range instances via its constructor or the `createRange*()` factory methods of
+ * {@link module:engine/model/model~Model} and {@link module:engine/model/writer~Writer}.
  */
 export default class Range {
 	/**
 	 * Creates a range spanning from `start` position to `end` position.
 	 *
-	 * **Note:** Constructor creates it's own {@link module:engine/model/position~Position Position} instances basing on passed values.
-	 *
-	 * **Note:** Should not be used directly outside the engine module.
-	 * Use {@link module:engine/model/writer~Writer#createRange writer#createRange()} method instead.
-	 * @see module:engine/model/writer~Writer#createRange
-	 * @see {@link module:engine/model/writer~Writer#createRange}
 	 * @param {module:engine/model/position~Position} start Start position.
 	 * @param {module:engine/model/position~Position} [end] End position. If not set, range will be collapsed at `start` position.
 	 */

+ 2 - 5
packages/ckeditor5-engine/src/model/treewalker.js

@@ -379,10 +379,7 @@ function formatReturnValue( type, item, previousPosition, nextPosition, length )
  * @property {module:engine/model/item~Item} item Item between old and new positions of {@link module:engine/model/treewalker~TreeWalker}.
  * @property {module:engine/model/position~Position} previousPosition Previous position of the iterator.
  * * Forward iteration: For `'elementEnd'` it is the last position inside the element. For all other types it is the
- * position before the item. Note that it is more efficient to use this position then calculate the position before
- * the node using {@link module:engine/model/model~createPositionBefore}. It is also more efficient to get the
- * position after node by shifting `previousPosition` by `length`, using {@link module:engine/model/position~Position#getShiftedBy},
- * then calculate the position using {@link module:engine/model/model~Model#createPositionAfter}.
+ * position before the item.
  * * Backward iteration: For `'elementStart'` it is the first position inside the element. For all other types it is
  * the position after item.
  * @property {module:engine/model/position~Position} nextPosition Next position of the iterator.
@@ -391,7 +388,7 @@ function formatReturnValue( type, item, previousPosition, nextPosition, length )
  * * Backward iteration: For `'elementEnd'` it is last position inside element. For all other types it is the position
  * before the item.
  * @property {Number} [length] Length of the item. For `'elementStart'` and `'character'` it is 1. For `'text'` it is
- * the length of the text. For `'elementEnd'` it is undefined.
+ * the length of the text. For `'elementEnd'` it is `undefined`.
  */
 
 /**

+ 16 - 12
packages/ckeditor5-engine/src/model/writer.js

@@ -545,7 +545,7 @@ export default class Writer {
 	}
 
 	/**
-	 * Shortcut for {@link module:engine/model/model~Model#createPositionFromPath model.createPositionFromPath()}.
+	 * Shortcut for {@link module:engine/model/model~Model#createPositionFromPath `Model#createPositionFromPath()`}.
 	 *
 	 * @param {module:engine/model/element~Element|module:engine/model/documentfragment~DocumentFragment} root Root of the position.
 	 * @param {Array.<Number>} path Position path. See {@link module:engine/model/position~Position#path}.
@@ -558,7 +558,7 @@ export default class Writer {
 	}
 
 	/**
-	 * Shortcut for {@link module:engine/model/model~Model#createPositionAt model.createPositionAt()}.
+	 * Shortcut for {@link module:engine/model/model~Model#createPositionAt `Model#createPositionAt()`}.
 	 *
 	 * @param {module:engine/model/item~Item|module:engine/model/position~Position} itemOrPosition
 	 * @param {Number|'end'|'before'|'after'} [offset] Offset or one of the flags. Used only when
@@ -570,7 +570,7 @@ export default class Writer {
 	}
 
 	/**
-	 * Shortcut for {@link module:engine/model/model~Model#createPositionAfter model.createPositionAfter()}.
+	 * Shortcut for {@link module:engine/model/model~Model#createPositionAfter `Model#createPositionAfter()`}.
 	 *
 	 * @param {module:engine/model/item~Item} item Item after which the position should be placed.
 	 * @returns {module:engine/model/position~Position}
@@ -580,7 +580,7 @@ export default class Writer {
 	}
 
 	/**
-	 * Shortcut for {@link module:engine/model/model~Model#createPositionBefore model.createPositionBefore()}.
+	 * Shortcut for {@link module:engine/model/model~Model#createPositionBefore `Model#createPositionBefore()`}.
 	 *
 	 * @param {module:engine/model/item~Item} item Item after which the position should be placed.
 	 * @returns {module:engine/model/position~Position}
@@ -590,7 +590,7 @@ export default class Writer {
 	}
 
 	/**
-	 * Shortcut for {@link module:engine/model/model~Model#createRange model.createRange()}.
+	 * Shortcut for {@link module:engine/model/model~Model#createRange `Model#createRange()`}.
 	 *
 	 * @param {module:engine/model/position~Position} start Start position.
 	 * @param {module:engine/model/position~Position} [end] End position. If not set, range will be collapsed at `start` position.
@@ -601,7 +601,7 @@ export default class Writer {
 	}
 
 	/**
-	 * Shortcut for {@link module:engine/model/model~Model#createRangeIn model.createRangeIn()}.
+	 * Shortcut for {@link module:engine/model/model~Model#createRangeIn `Model#createRangeIn()`}.
 	 *
 	 * @param {module:engine/model/element~Element} element Element which is a parent for the range.
 	 * @returns {module:engine/model/range~Range}
@@ -611,7 +611,7 @@ export default class Writer {
 	}
 
 	/**
-	 * Shortcut for {@link module:engine/model/model~Model#createRangeOn model.createRangeOn()}.
+	 * Shortcut for {@link module:engine/model/model~Model#createRangeOn `Model#createRangeOn()`}.
 	 *
 	 * @param {module:engine/model/element~Element} element Element which is a parent for the range.
 	 * @returns {module:engine/model/range~Range}
@@ -621,7 +621,7 @@ export default class Writer {
 	}
 
 	/**
-	 * Shortcut for {@link module:engine/model/model~Model#createSelection model.createSelection()}.
+	 * Shortcut for {@link module:engine/model/model~Model#createSelection `Model#createSelection()`}.
 	 *
 	 * @param {module:engine/model/selection~Selection|module:engine/model/documentselection~DocumentSelection|
 	 * module:engine/model/position~Position|module:engine/model/element~Element|
@@ -1067,10 +1067,14 @@ export default class Writer {
 	}
 
 	/**
-	 * Sets this selection's ranges and direction to the specified location based on the given
-	 * {@link module:engine/model/selection~Selection selection}, {@link module:engine/model/position~Position position},
-	 * {@link module:engine/model/node~Node node}, {@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 null.
+	 * Sets the document's selection (ranges and direction) to the specified location based on:
+	 *
+	 * * the given {@link module:engine/model/selection~Selection selection},
+	 * * or the given {@link module:engine/model/position~Position position},
+	 * * or the given {@link module:engine/model/range~Range range},
+	 * * or the given iterable of {@link module:engine/model/range~Range ranges},
+	 * * or the given {@link module:engine/model/node~Node node},
+	 * * or `null`.
 	 *
 	 *		// Sets selection to the given range.
 	 *		const range = writer.createRange( start, end );

+ 7 - 13
packages/ckeditor5-engine/src/view/documentselection.js

@@ -12,20 +12,14 @@ import mix from '@ckeditor/ckeditor5-utils/src/mix';
 import EmitterMixin from '@ckeditor/ckeditor5-utils/src/emittermixin';
 
 /**
- * Class representing document selection in tree view. It's instance is stored at
- * {@link module:engine/view/document~Document#selection}. It is similar to {@link module:engine/view/selection~Selection} but
- * it has read-only API and can be modified only by writer obtained from {@link module:engine/view/view~View#change} method.
+ * Class representing the document selection in the view.
  *
- * Selection can consist of {@link module:engine/view/range~Range ranges}.
- * Selection's ranges can be obtained via {@link module:engine/view/documentselection~DocumentSelection#getRanges getRanges},
- * {@link module:engine/view/documentselection~DocumentSelection#getFirstRange getFirstRange}
- * and {@link module:engine/view/documentselection~DocumentSelection#getLastRange getLastRange}
- * methods, which return copies of ranges stored inside selection. Modifications made on these copies will not change
- * selection's state. Similar situation occurs when getting {@link module:engine/view/documentselection~DocumentSelection#anchor anchor},
- * {@link module:engine/view/documentselection~DocumentSelection#focus focus},
- * {@link module:engine/view/documentselection~DocumentSelection#getFirstPosition first} and
- * {@link module:engine/view/documentselection~DocumentSelection#getLastPosition last} positions - all will return
- * copies of requested positions.
+ * Its instance is available in {@link module:engine/view/document~Document#selection `Document#selection`}.
+ *
+ * It is similar to {@link module:engine/view/selection~Selection} but
+ * it has a read-only API and can be modified only by the writer available in
+ * the {@link module:engine/view/view~View#change `View#change()`} block
+ * (so via {@link module:engine/view/downcastwriter~DowncastWriter#setSelection `DowncastWriter#setSelection()`}).
  */
 export default class DocumentSelection {
 	/**

+ 10 - 6
packages/ckeditor5-engine/src/view/downcastwriter.js

@@ -22,11 +22,15 @@ import EditableElement from './editableelement';
 import { isPlainObject } from 'lodash-es';
 
 /**
- * View downcast writer class. Provides set of methods used to properly manipulate nodes attached to
- * {@link module:engine/view/document~Document view document}. It is not recommended to use it directly. To get an instance
- * of view writer associated with the document use {@link module:engine/view/view~View#change view.change()) method.
- * The `DowncastWriter` is designed to work with semantic view which is the view downcasted from model. For working with
- * ordinary view (e.g. parsed from string) {@link module:engine/view/upcastwriter~UpcastWriter upcast writer} should be used.
+ * View downcast writer.
+ *
+ * It provides a set of methods used to manipulate view nodes.
+ *
+ * The `DowncastWriter` is designed to work with semantic views which are the views that were/are being downcasted from the model.
+ * To work with ordinary views (e.g. parsed from a string) use the {@link module:engine/view/upcastwriter~UpcastWriter upcast writer}.
+ *
+ * Do not create an instance of this writer manually. To modify a view structure, use
+ * the {@link module:engine/view/view~View#change View#change()) block.
  */
 export default class DowncastWriter {
 	constructor( document ) {
@@ -53,7 +57,7 @@ export default class DowncastWriter {
 	 * {@link module:engine/view/item~Item item}, {@link module:engine/view/range~Range range},
 	 * an iterable of {@link module:engine/view/range~Range ranges} or null.
 	 *
-	 * ### Usage:
+	 * Usage:
 	 *
 	 *		// Sets selection to the given range.
 	 *		const range = writer.createRange( start, end );

+ 4 - 4
packages/ckeditor5-engine/src/view/position.js

@@ -325,14 +325,14 @@ export default class Position {
 				return this._createAfter( node );
 			} else if ( offset !== 0 && !offset ) {
 				/**
-				 * {@link module:engine/view/position~Position.createAt `Position.createAt()`}
+				 * {@link module:engine/view/view~View#createPositionAt `View#createPositionAt()`}
 				 * requires the offset to be specified when the first parameter is a view item.
 				 *
-				 * @error view-position-createAt-offset-required
+				 * @error view-createPositionAt-offset-required
 				 */
 				throw new CKEditorError(
-					'view-position-createAt-offset-required: ' +
-					'Position.createAt() requires the offset when the first parameter is a view item.' );
+					'view-createPositionAt-offset-required: ' +
+					'View#createPositionAt() requires the offset when the first parameter is a view item.' );
 			}
 
 			return new Position( node, offset );

+ 13 - 16
packages/ckeditor5-engine/src/view/selection.js

@@ -19,28 +19,25 @@ import isIterable from '@ckeditor/ckeditor5-utils/src/isiterable';
 import DocumentSelection from './documentselection';
 
 /**
- * Class representing selection in tree view.
+ * Class representing an arbirtary selection in the view.
+ * See also {@link module:engine/view/documentselection~DocumentSelection}.
  *
- * Selection can consist of {@link module:engine/view/range~Range ranges} that can be set using
- * {@link module:engine/view/selection~Selection#setTo setTo} method.
- * That method create copies of provided ranges and store those copies internally. Further modifications to passed
- * ranges will not change selection's state.
- * Selection's ranges can be obtained via {@link module:engine/view/selection~Selection#getRanges getRanges},
- * {@link module:engine/view/selection~Selection#getFirstRange getFirstRange} and
- * {@link module:engine/view/selection~Selection#getLastRange getLastRange} methods, which return copies of ranges
- * stored inside selection. Modifications made on these copies will not change selection's state. Similar situation
- * occurs when getting {@link module:engine/view/selection~Selection#anchor anchor},
- * {@link module:engine/view/selection~Selection#focus focus}, {@link module:engine/view/selection~Selection#getFirstPosition first}
- * and {@link module:engine/view/selection~Selection#getLastPosition last} positions - all will return
- * copies of requested positions.
+ * New selection instances can be created via the constructor or one these methods:
+ *
+ * * {@link module:engine/view/view~View#createSelection `View#createSelection()`},
+ * * {@link module:engine/view/upcastwriter~UpcastWriter#createSelection `UpcastWriter#createSelection()`}.
+ *
+ * A selection can consist of {@link module:engine/view/range~Range ranges} that can be set by using
+ * the {@link module:engine/view/selection~Selection#setTo `Selection#setTo()`} method.
  */
 export default class Selection {
 	/**
 	 * Creates new selection instance.
 	 *
-	 * **Note**: The selection constructor is available as factory method:
-	 * - {@link module:engine/view/view~View#createSelection()}
-	 * - {@link module:engine/view/downcastwriter~DowncastWriter#createSelection()}.
+	 * **Note**: The selection constructor is available as a factory method:
+	 *
+	 * * {@link module:engine/view/view~View#createSelection `View#createSelection()`},
+	 * * {@link module:engine/view/upcastwriter~UpcastWriter#createSelection `UpcastWriter#createSelection()`}.
 	 *
 	 * 		// Creates empty selection without ranges.
 	 *		const selection = writer.createSelection();

+ 7 - 7
packages/ckeditor5-engine/src/view/treewalker.js

@@ -464,24 +464,24 @@ export default class TreeWalker {
  *
  * @typedef {Object} module:engine/view/treewalker~TreeWalkerValue
  * @property {module:engine/view/treewalker~TreeWalkerValueType} type
- * @property {module:engine/view/item~Item} item Item between old and new positions of {@link module:engine/view/treewalker~TreeWalker}.
+ * @property {module:engine/view/item~Item} item Item between the old and the new positions
+ * of the tree walker.
  * @property {module:engine/view/position~Position} previousPosition Previous position of the iterator.
  * * Forward iteration: For `'elementEnd'` it is the last position inside the element. For all other types it is the
- * position before the item. Note that it is more efficient to use this position then calculate the position before
- * the node using {@link module:engine/view/view~view.createPositionBefore}.
+ * position before the item.
  * * Backward iteration: For `'elementStart'` it is the first position inside the element. For all other types it is
  * the position after item.
  * * If the position is at the beginning or at the end of the {@link module:engine/view/text~Text} it is always moved from the
- * inside of the Text to its parent just before or just after Text.
+ * inside of the text to its parent just before or just after that text.
  * @property {module:engine/view/position~Position} nextPosition Next position of the iterator.
  * * Forward iteration: For `'elementStart'` it is the first position inside the element. For all other types it is
  * the position after the item.
  * * Backward iteration: For `'elementEnd'` it is last position inside element. For all other types it is the position
  * before the item.
  * * If the position is at the beginning or at the end of the {@link module:engine/view/text~Text} it is always moved from the
- * inside of the Text to its parent just before or just after Text.
- * @property {Number} [length] Length of the item. For `'elementStart'` it is 1. For `'text'` it is
- * the length of the text. For `'elementEnd'` it is undefined.
+ * inside of the text to its parent just before or just after that text.
+ * @property {Number} [length] Length of the item. For `'elementStart'` it is `1`. For `'text'` it is
+ * the length of that text. For `'elementEnd'` it is `undefined`.
  */
 
 /**

+ 10 - 7
packages/ckeditor5-engine/src/view/upcastwriter.js

@@ -14,14 +14,17 @@ import Range from './range';
 import Selection from './selection';
 
 /**
- * View upcast writer class. Provides set of methods used to properly manipulate nodes attached to
- * {@link module:engine/view/view~View view instance}. It should be only used to manipulate non-semantic view
- * (view created from HTML string). For view which was downcasted from the {@link module:engine/model/model~Model model}
- * see {@link module:engine/view/downcastwriter~DowncastWriter writer}.
+ * View upcast writer.
+ *
+ * It provides a set of methods used to manipulate view nodes.
+ * It should be used only while working on a non-semantic view
+ * (e.g. a view created from HTML string on paste).
+ * To manipulate a view which was or is being downcasted from the the model use the
+ * {@link module:engine/view/downcastwriter~DowncastWriter downcast writer}.
  */
 export default class UpcastWriter {
 	/**
-	 * Clones provided element.
+	 * Clones the provided element.
 	 *
 	 * @see module:engine/view/element~Element#_clone
 	 * @param {module:engine/view/element~Element} element Element to be cloned.
@@ -65,7 +68,7 @@ export default class UpcastWriter {
 	}
 
 	/**
-	 * Removes number of child nodes starting at the given index and set the parent of these nodes to `null`.
+	 * Removes the given number of child nodes starting at the given index and set the parent of these nodes to `null`.
 	 *
 	 * @see module:engine/view/element~Element#_removeChildren
 	 * @param {Number} index Offset from which nodes will be removed.
@@ -325,7 +328,7 @@ export default class UpcastWriter {
 	}
 
 	/**
-	 Creates new {@link module:engine/view/selection~Selection} instance.
+	 * Creates a new {@link module:engine/view/selection~Selection} instance.
 	 *
 	 * 		// Creates empty selection without ranges.
 	 *		const selection = writer.createSelection();

+ 1 - 1
packages/ckeditor5-engine/tests/model/position.js

@@ -130,7 +130,7 @@ describe( 'Position', () => {
 	describe( 'static creators', () => {
 		describe( '_createAt()', () => {
 			it( 'should throw if no offset is passed', () => {
-				expect( () => Position._createAt( ul ) ).to.throw( CKEditorError, /model-position-createAt-offset-required/ );
+				expect( () => Position._createAt( ul ) ).to.throw( CKEditorError, /model-createPositionAt-offset-required/ );
 			} );
 
 			it( 'should create positions from positions', () => {

+ 1 - 1
packages/ckeditor5-engine/tests/model/range.js

@@ -185,7 +185,7 @@ describe( 'Range', () => {
 			} );
 		} );
 
-		describe( '_createFromRange()', () => {
+		describe( 'clone()', () => {
 			it( 'should create a new instance of Range that is equal to passed range', () => {
 				const clone = range.clone();
 

+ 1 - 1
packages/ckeditor5-engine/tests/view/position.js

@@ -383,7 +383,7 @@ describe( 'Position', () => {
 			it( 'should throw if no offset is passed', () => {
 				const element = new Element( 'p' );
 
-				expect( () => Position._createAt( element ) ).to.throw( CKEditorError, /view-position-createAt-offset-required/ );
+				expect( () => Position._createAt( element ) ).to.throw( CKEditorError, /view-createPositionAt-offset-required/ );
 			} );
 
 			it( 'should create positions from positions', () => {