Bladeren bron

Docs: Update documentation on Position/Range/Selection factory methods.

Maciej Gołaszewski 7 jaren geleden
bovenliggende
commit
446600a48e

+ 8 - 2
packages/ckeditor5-engine/src/conversion/upcastdispatcher.js

@@ -71,10 +71,16 @@ import mix from '@ckeditor/ckeditor5-utils/src/mix';
  *  	 				conversionApi.writer.insert( paragraph, splitResult.position );
  *
  *  	 				// Convert children to paragraph.
- *  	 				const { modelRange } = conversionApi.convertChildren( data.viewItem, Position.createAt( paragraph, 0 ) );
+ *  	 				const { modelRange } = conversionApi.convertChildren(
+ *  	 					data.viewItem,
+ *  	 					conversionApi.writer.createPositionAt( paragraph, 0 )
+ *  	 				);
  *
  * 						// Set as conversion result, attribute converters may use this property.
- *  	 				data.modelRange = new Range( Position.createBefore( paragraph ), modelRange.end );
+ *  	 				data.modelRange = conversionApi.writer.createRange(
+ *  	 					conversionApi.writer.createPositionBefore( paragraph ),
+ *  	 					modelRange.end
+ *  	 				);
  *
  *  	 				// Continue conversion inside paragraph.
  *  	 				data.modelCursor = data.modelRange.end;

+ 158 - 15
packages/ckeditor5-engine/src/model/model.js

@@ -309,16 +309,16 @@ export default class Model {
 	 *
 	 *		// Insert text at given position - document selection will not be modified.
 	 *		editor.model.change( writer => {
-	 *			editor.model.insertContent( writer.createText( 'x' ), Position.createAt( doc.getRoot(), 2 ) );
+	 *			editor.model.insertContent( writer.createText( 'x' ), writer.createPositionAt( doc.getRoot(), 2 ) );
 	 *		} );
 	 *
 	 * If an instance of {@link module:engine/model/selection~Selection} is passed as `selectable`
 	 * it will be moved to the target position (where the document selection should be moved after the insertion).
 	 *
-	 *		// Insert text replacing given selection instance.
-	 *		const selection = new Selection( paragraph, 'in' );
-	 *
 	 *		editor.model.change( writer => {
+	 *			// Insert text replacing given selection instance.
+	 *			const selection = writer.createSelection( paragraph, 'in' );
+	 *
 	 *			editor.model.insertContent( writer.createText( 'x' ), selection );
 	 *
 	 *			// insertContent() modifies the passed selection instance so it can be used to set the document selection.
@@ -470,6 +470,22 @@ export default class Model {
 		return false;
 	}
 
+	/**
+	 * Creates a position.
+	 *
+	 * **Note:** This method is also available on `writer` instance 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}.
+	 * @param {module:engine/model/position~PositionStickiness} [stickiness='toNone'] Position stickiness.
+	 * See {@link module:engine/model/position~PositionStickiness}.
+	 * @returns {module:engine/model/position~Position}
+	 */
+	createPositionFromPath( root, path, stickiness ) {
+		return new ModelPosition( root, path, stickiness );
+	}
+
 	/**
 	 * Creates position at the given location. The location can be specified as:
 	 *
@@ -478,10 +494,13 @@ export default class Model {
 	 * * 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).
 	 *
-	 * This method is a shortcut to other constructors such as:
+	 * This method is a shortcut to other factory methods such as:
+	 *
+	 * * {@link module:engine/model/model~Model#createBefore},
+	 * * {@link module:engine/model/model~Model#createAfter}.
 	 *
-	 * * {@link module:engine/model/position~Position._createBefore},
-	 * * {@link module:engine/model/position~Position._createAfter},
+	 * **Note:** This method is also available on `writer` instance 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
@@ -494,6 +513,9 @@ export default class Model {
 	/**
 	 * Creates a new position, after 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()}:
+	 *
 	 * @param {module:engine/model/item~Item} item Item after which the position should be placed.
 	 * @returns {module:engine/model/position~Position}
 	 */
@@ -501,30 +523,151 @@ export default class Model {
 		return ModelPosition._createAfter( 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()}:
+	 *
+	 * @param {module:engine/model/item~Item} item Item before which the position should be placed.
+	 * @returns {module:engine/model/position~Position}
+	 */
 	createPositionBefore( item ) {
 		return ModelPosition._createBefore( item );
 	}
 
-	createPositionFromPath( root, path ) {
-		return new ModelPosition( root, path );
-	}
-
+	/**
+	 * Creates a range spanning from `start` position to `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()}:
+	 *
+	 *		model.change( writer => {
+	 *			const range = writer.createRange( paragraph );
+	 *		} );
+	 *
+	 * @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.
+	 * @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
+	 * 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()}:
+	 *
+	 *		model.change( writer => {
+	 *			const range = writer.createRangeIn( paragraph );
+	 *		} );
+	 *
+	 * @param {module:engine/model/element~Element} element Element which is a parent for the range.
+	 * @returns {module:engine/model/range~Range}
+	 */
 	createRangeIn( element ) {
 		return ModelRange._createIn( element );
 	}
 
-	createRangeOn( element ) {
-		return ModelRange._createOn( element );
+	/**
+	 * Creates a range that starts before 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()}:
+	 *
+	 *		model.change( writer => {
+	 *			const range = writer.createRangeOn( paragraph );
+	 *		} );
+	 *
+	 * @param {module:engine/model/item~Item} item
+	 * @returns {module:engine/model/range~Range}
+	 */
+	createRangeOn( item ) {
+		return ModelRange._createOn( item );
 	}
 
-	createSelection( selectable ) {
-		return new ModelSelection( selectable );
+	/**
+	 * 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.
+	 *
+	 * **Note:** This method is also available on `writer` instance as
+	 * {@link module:engine/model/writer~Writer#createSelection writer.createSelection()}:
+	 *
+	 *		// Creates empty selection without ranges.
+	 *		const selection = writer.createSelection();
+	 *
+	 *		// Creates selection at the given range.
+	 *		const range = writer.createRange( start, end );
+	 *		const selection = writer.createSelection( range );
+	 *
+	 *		// Creates selection at the given ranges
+	 *		const ranges = [ writer.createRange( start1, end2 ), writer.createRange( star2, end2 ) ];
+	 *		const selection = writer.createSelection( ranges );
+	 *
+	 *		// Creates selection from the other selection.
+	 *		// Note: It doesn't copies selection attributes.
+	 *		const otherSelection = writer.createSelection();
+	 *		const selection = writer.createSelection( otherSelection );
+	 *
+	 *		// Creates selection from the given document selection.
+	 *		// Note: It doesn't copies selection attributes.
+	 *		const documentSelection = new DocumentSelection( doc );
+	 *		const selection = writer.createSelection( documentSelection );
+	 *
+	 *		// Creates selection at the given position.
+	 *		const position = writer.createPositionFromPath( root, path );
+	 *		const selection = writer.createSelection( position );
+	 *
+	 *		// Creates selection at the given offset in the given element.
+	 *		const paragraph = writer.createElement( 'paragraph' );
+	 *		const selection = writer.createSelection( paragraph, offset );
+	 *
+	 *		// Creates a range inside an {@link module:engine/model/element~Element element} which starts before the
+	 *		// first child of that element and ends after the last child of that element.
+	 *		const selection = writer.createSelection( paragraph, 'in' );
+	 *
+	 *		// Creates a range on an {@link module:engine/model/item~Item item} which starts before the item and ends
+	 *		// just after the item.
+	 *		const selection = writer.createSelection( paragraph, 'on' );
+	 *
+	 * Selection's constructor allow passing additional options (`'backward'`) as the last argument.
+	 *
+	 *		// Creates backward selection.
+	 *		const selection = writer.createSelection( range, { backward: true } );
+	 *
+	 * @param {module:engine/model/selection~Selection|module:engine/model/documentselection~DocumentSelection|
+	 * module:engine/model/position~Position|module:engine/model/element~Element|
+	 * Iterable.<module:engine/model/range~Range>|module:engine/model/range~Range|null} selectable
+	 * @param {Number|'before'|'end'|'after'|'on'|'in'} [placeOrOffset] Sets place or offset of the selection.
+	 * @param {Object} [options]
+	 * @param {Boolean} [options.backward] Sets this selection instance to be backward.
+	 * @returns {module:engine/model/selection~Selection}
+	 */
+	createSelection( selectable, placeOrOffset, options ) {
+		return new ModelSelection( selectable, placeOrOffset, options );
 	}
 
+	/**
+	 * Creates a {@link module:engine/model/batch~Batch} instance.
+	 *
+	 * **Note:** In most cases creating a batch instance is not necessary as they are created when using:
+	 *
+	 * * {@link #change},
+	 * * {@link #enqueueChange}.
+	 *
+	 * @returns {module:engine/model/batch~Batch}
+	 */
 	createBatch() {
 		return new Batch();
 	}

+ 4 - 5
packages/ckeditor5-engine/src/model/position.js

@@ -751,9 +751,9 @@ export default class Position {
 	 *
 	 * Example:
 	 *
-	 *		let original = new Position( root, [ 2, 3, 1 ] );
-	 *		let source = new Position( root, [ 2, 2 ] );
-	 *		let target = new Position( otherRoot, [ 1, 1, 3 ] );
+	 *		let original = model.createPositionFromPath( root, [ 2, 3, 1 ] );
+	 *		let source = model.createPositionFromPath( root, [ 2, 2 ] );
+	 *		let target = model.createPositionFromPath( otherRoot, [ 1, 1, 3 ] );
 	 *		original._getCombined( source, target ); // path is [ 1, 1, 4, 1 ], root is `otherRoot`
 	 *
 	 * Explanation:
@@ -811,8 +811,7 @@ export default class Position {
 	 * This method is a shortcut to other factory methods such as:
 	 *
 	 * * {@link module:engine/model/position~Position._createBefore},
-	 * * {@link module:engine/model/position~Position._createAfter},
-	 * * {@link module:engine/model/position~Position._createAt}.
+	 * * {@link module:engine/model/position~Position._createAfter}.
 	 *
 	 * @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

+ 25 - 12
packages/ckeditor5-engine/src/model/range.js

@@ -21,6 +21,10 @@ export default class Range {
 	 *
 	 * **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.
 	 */
@@ -165,16 +169,19 @@ export default class Range {
 	 *
 	 * Examples:
 	 *
-	 *		let range = new Range( new Position( root, [ 2, 7 ] ), new Position( root, [ 4, 0, 1 ] ) );
-	 *		let otherRange = new Range( new Position( root, [ 1 ] ), new Position( root, [ 5 ] ) );
+	 *		let range = model.createRange(
+	 *			model.createPositionFromPath( root, [ 2, 7 ] ),
+	 *			model.createPositionFromPath( root, [ 4, 0, 1 ] )
+	 *		);
+	 *		let otherRange = model.createRange( model.createPositionFromPath( root, [ 1 ] ), model.createPositionFromPath( root, [ 5 ] ) );
 	 *		let transformed = range.getDifference( otherRange );
 	 *		// transformed array has no ranges because `otherRange` contains `range`
 	 *
-	 *		otherRange = new Range( new Position( root, [ 1 ] ), new Position( root, [ 3 ] ) );
+	 *		otherRange = model.createRange( model.createPositionFromPath( root, [ 1 ] ), model.createPositionFromPath( root, [ 3 ] ) );
 	 *		transformed = range.getDifference( otherRange );
 	 *		// transformed array has one range: from [ 3 ] to [ 4, 0, 1 ]
 	 *
-	 *		otherRange = new Range( new Position( root, [ 3 ] ), new Position( root, [ 4 ] ) );
+	 *		otherRange = model.createRange( model.createPositionFromPath( root, [ 3 ] ), model.createPositionFromPath( root, [ 4 ] ) );
 	 *		transformed = range.getDifference( otherRange );
 	 *		// transformed array has two ranges: from [ 2, 7 ] to [ 3 ] and from [ 4 ] to [ 4, 0, 1 ]
 	 *
@@ -212,11 +219,14 @@ export default class Range {
 	 *
 	 * Examples:
 	 *
-	 *		let range = new Range( new Position( root, [ 2, 7 ] ), new Position( root, [ 4, 0, 1 ] ) );
-	 *		let otherRange = new Range( new Position( root, [ 1 ] ), new Position( root, [ 2 ] ) );
+	 *		let range = model.createRange(
+	 *			model.createPositionFromPath( root, [ 2, 7 ] ),
+	 *			model.createPositionFromPath( root, [ 4, 0, 1 ] )
+	 *		);
+	 *		let otherRange = model.createRange( model.createPositionFromPath( root, [ 1 ] ), model.createPositionFromPath( root, [ 2 ] ) );
 	 *		let transformed = range.getIntersection( otherRange ); // null - ranges have no common part
 	 *
-	 *		otherRange = new Range( new Position( root, [ 3 ] ), new Position( root, [ 5 ] ) );
+	 *		otherRange = model.createRange( model.createPositionFromPath( root, [ 3 ] ), model.createPositionFromPath( root, [ 5 ] ) );
 	 *		transformed = range.getIntersection( otherRange ); // range from [ 3 ] to [ 4, 0, 1 ]
 	 *
 	 * @param {module:engine/model/range~Range} otherRange Range to check for intersection.
@@ -603,17 +613,20 @@ export default class Range {
 	 *
 	 * Examples:
 	 *
-	 *		let range = new Range( new Position( root, [ 2, 7 ] ), new Position( root, [ 4, 0, 1 ] ) );
-	 *		let transformed = range._getTransformedByInsertion( new Position( root, [ 1 ] ), 2 );
+	 *		let range = model.createRange(
+	 *			model.createPositionFromPath( root, [ 2, 7 ] ),
+	 *			model.createPositionFromPath( root, [ 4, 0, 1 ] )
+	 *		);
+	 *		let transformed = range._getTransformedByInsertion( model.createPositionFromPath( root, [ 1 ] ), 2 );
 	 *		// transformed array has one range from [ 4, 7 ] to [ 6, 0, 1 ]
 	 *
-	 *		transformed = range._getTransformedByInsertion( new Position( root, [ 4, 0, 0 ] ), 4 );
+	 *		transformed = range._getTransformedByInsertion( model.createPositionFromPath( root, [ 4, 0, 0 ] ), 4 );
 	 *		// transformed array has one range from [ 2, 7 ] to [ 4, 0, 5 ]
 	 *
-	 *		transformed = range._getTransformedByInsertion( new Position( root, [ 3, 2 ] ), 4 );
+	 *		transformed = range._getTransformedByInsertion( model.createPositionFromPath( root, [ 3, 2 ] ), 4 );
 	 *		// transformed array has one range, which is equal to original range
 	 *
-	 *		transformed = range._getTransformedByInsertion( new Position( root, [ 3, 2 ] ), 4, true );
+	 *		transformed = range._getTransformedByInsertion( model.createPositionFromPath( root, [ 3, 2 ] ), 4, true );
 	 *		// transformed array has two ranges: from [ 2, 7 ] to [ 3, 2 ] and from [ 3, 6 ] to [ 4, 0, 1 ]
 	 *
 	 * @protected

+ 19 - 19
packages/ckeditor5-engine/src/model/selection.js

@@ -36,46 +36,46 @@ export default class Selection {
 	 * or creates an empty selection if no arguments were passed.
 	 *
 	 *		// Creates empty selection without ranges.
-	 *		const selection = new Selection();
+	 *		const selection = writer.createSelection();
 	 *
 	 *		// Creates selection at the given range.
-	 *		const range = new Range( start, end );
-	 *		const selection = new Selection( range );
+	 *		const range = writer.createRange( start, end );
+	 *		const selection = writer.createSelection( range );
 	 *
 	 *		// Creates selection at the given ranges
-	 *		const ranges = [ new Range( start1, end2 ), new Range( star2, end2 ) ];
-	 *		const selection = new Selection( ranges );
+	 *		const ranges = [ writer.createRange( start1, end2 ), writer.createRange( star2, end2 ) ];
+	 *		const selection = writer.createSelection( ranges );
 	 *
 	 *		// Creates selection from the other selection.
 	 *		// Note: It doesn't copies selection attributes.
-	 *		const otherSelection = new Selection();
-	 *		const selection = new Selection( otherSelection );
+	 *		const otherSelection = writer.createSelection();
+	 *		const selection = writer.createSelection( otherSelection );
 	 *
 	 *		// Creates selection from the given document selection.
 	 *		// Note: It doesn't copies selection attributes.
 	 *		const documentSelection = new DocumentSelection( doc );
-	 *		const selection = new Selection( documentSelection );
+	 *		const selection = writer.createSelection( documentSelection );
 	 *
 	 *		// Creates selection at the given position.
-	 *		const position = new Position( root, path );
-	 *		const selection = new Selection( position );
+	 *		const position = writer.createPositionFromPath( root, path );
+	 *		const selection = writer.createSelection( position );
 	 *
 	 *		// Creates selection at the given offset in the given element.
 	 *		const paragraph = writer.createElement( 'paragraph' );
-	 *		const selection = new Selection( paragraph, offset );
+	 *		const selection = writer.createSelection( paragraph, offset );
 	 *
 	 *		// Creates a range inside an {@link module:engine/model/element~Element element} which starts before the
 	 *		// first child of that element and ends after the last child of that element.
-	 *		const selection = new Selection( paragraph, 'in' );
+	 *		const selection = writer.createSelection( paragraph, 'in' );
 	 *
 	 *		// Creates a range on an {@link module:engine/model/item~Item item} which starts before the item and ends
 	 *		// just after the item.
-	 *		const selection = new Selection( paragraph, 'on' );
+	 *		const selection = writer.createSelection( paragraph, 'on' );
 	 *
 	 * Selection's constructor allow passing additional options (`'backward'`) as the last argument.
 	 *
 	 *		// Creates backward selection.
-	 *		const selection = new Selection( range, { backward: true } );
+	 *		const selection = writer.createSelection( range, { backward: true } );
 	 *
 	 * @param {module:engine/model/selection~Selection|module:engine/model/documentselection~DocumentSelection|
 	 * module:engine/model/position~Position|module:engine/model/element~Element|
@@ -330,16 +330,16 @@ export default class Selection {
 	 *		selection.setTo( null );
 	 *
 	 *		// Sets selection to the given range.
-	 *		const range = new Range( start, end );
+	 *		const range = writer.createRange( start, end );
 	 *		selection.setTo( range );
 	 *
 	 *		// Sets selection to given ranges.
-	 *		const ranges = [ new Range( start1, end2 ), new Range( star2, end2 ) ];
+	 *		const ranges = [ writer.createRange( start1, end2 ), writer.createRange( star2, end2 ) ];
 	 *		selection.setTo( ranges );
 	 *
 	 *		// Sets selection to other selection.
 	 *		// Note: It doesn't copies selection attributes.
-	 *		const otherSelection = new Selection();
+	 *		const otherSelection = writer.createSelection();
 	 *		selection.setTo( otherSelection );
 	 *
 	 *		// Sets selection to the given document selection.
@@ -348,7 +348,7 @@ export default class Selection {
 	 *		selection.setTo( documentSelection );
 	 *
 	 *		// Sets collapsed selection at the given position.
-	 *		const position = new Position( root, path );
+	 *		const position = writer.createPositionFromPath( root, path );
 	 *		selection.setTo( position );
 	 *
 	 *		// Sets collapsed selection at the position of the given node and an offset.
@@ -366,7 +366,7 @@ export default class Selection {
 	 * `Selection#setTo()`' method allow passing additional options (`backward`) as the last argument.
 	 *
 	 *		// Sets backward selection.
-	 *		const selection = new Selection( range, { backward: true } );
+	 *		const selection = writer.createSelection( range, { backward: true } );
 	 *
 	 * @param {module:engine/model/selection~Selection|module:engine/model/documentselection~DocumentSelection|
 	 * module:engine/model/position~Position|module:engine/model/node~Node|

+ 69 - 10
packages/ckeditor5-engine/src/model/writer.js

@@ -544,36 +544,95 @@ export default class Writer {
 		}
 	}
 
+	/**
+	 * 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}.
+	 * @param {module:engine/model/position~PositionStickiness} [stickiness='toNone'] Position stickiness.
+	 * See {@link module:engine/model/position~PositionStickiness}.
+	 * @returns {module:engine/model/position~Position}
+	 */
+	createPositionFromPath( root, path, stickiness ) {
+		return this.model.createPositionFromPath( root, path, stickiness );
+	}
+
+	/**
+	 * 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
+	 * first parameter is a {@link module:engine/model/item~Item model item}.
+	 * @returns {module:engine/model/position~Position}
+	 */
 	createPositionAt( itemOrPosition, offset ) {
 		return this.model.createPositionAt( itemOrPosition, offset );
 	}
 
+	/**
+	 * 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}
+	 */
 	createPositionAfter( item ) {
 		return this.model.createPositionAfter( item );
 	}
 
+	/**
+	 * 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}
+	 */
 	createPositionBefore( item ) {
 		return this.model.createPositionBefore( item );
 	}
 
-	createPositionFromPath( root, path ) {
-		return this.model.createPositionFromPath( root, path );
-	}
-
+	/**
+	 * 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.
+	 * @returns {module:engine/model/range~Range}
+	 */
 	createRange( start, end ) {
 		return this.model.createRange( start, end );
 	}
 
+	/**
+	 * 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}
+	 */
 	createRangeIn( element ) {
 		return this.model.createRangeIn( element );
 	}
 
+	/**
+	 * 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}
+	 */
 	createRangeOn( element ) {
 		return this.model.createRangeOn( element );
 	}
 
-	createSelection( selectable ) {
-		return this.model.createSelection( selectable );
+	/**
+	 * 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|
+	 * Iterable.<module:engine/model/range~Range>|module:engine/model/range~Range|null} selectable
+	 * @param {Number|'before'|'end'|'after'|'on'|'in'} [placeOrOffset] Sets place or offset of the selection.
+	 * @param {Object} [options]
+	 * @param {Boolean} [options.backward] Sets this selection instance to be backward.
+	 * @returns {module:engine/model/selection~Selection}
+	 */
+	createSelection( selectable, placeOrOffset, options ) {
+		return this.model.createSelection( selectable, placeOrOffset, options );
 	}
 
 	/**
@@ -1014,15 +1073,15 @@ export default class Writer {
 	 * {@link module:engine/model/range~Range range}, an iterable of {@link module:engine/model/range~Range ranges} or null.
 	 *
 	 *		// Sets selection to the given range.
-	 *		const range = new Range( start, end );
+	 *		const range = writer.createRange( start, end );
 	 *		writer.setSelection( range );
 	 *
 	 *		// Sets selection to given ranges.
-	 *		const ranges = [ new Range( start1, end2 ), new Range( star2, end2 ) ];
+	 *		const ranges = [ writer.createRange( start1, end2 ), writer.createRange( star2, end2 ) ];
 	 *		writer.setSelection( range );
 	 *
 	 *		// Sets selection to other selection.
-	 *		const otherSelection = new Selection();
+	 *		const otherSelection = writer.createSelection();
 	 *		writer.setSelection( otherSelection );
 	 *
 	 *		// Sets selection to the given document selection.
@@ -1030,7 +1089,7 @@ export default class Writer {
 	 *		writer.setSelection( documentSelection );
 	 *
 	 *		// Sets collapsed selection at the given position.
-	 *		const position = new Position( root, path );
+	 *		const position = writer.createPosition( root, path );
 	 *		writer.setSelection( position );
 	 *
 	 *		// Sets collapsed selection at the position of the given node and an offset.