Docs: A lot of corrections all across the docs.

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 );
@@ -87,15 +87,6 @@ export default class LiveRange extends Range {
 	 * @returns {module:engine/model/liverange~LiveRange}
 	 */
 
-	/**
-	 * @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}.

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,32 +542,30 @@ 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 ) {
 		return new ModelRange( start, end );
 	}
 
 	/**
-	 * 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}
 	 */

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' ) ) {

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.
 	 */

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`.
  */
 
 /**