Docs improvements.

src/model/selection.js

@@ -36,11 +36,11 @@ export default class Selection {
 	 *
 	 *		// Creates selection at the given range.
 	 *		const range = new Range( start, end );
-	 *		const selection = new Selection( range, { backward } );
+	 *		const selection = new Selection( range );
 	 *
 	 *		// Creates selection at the given ranges
 	 * 		const ranges = [ new Range( start1, end2 ), new Range( star2, end2 ) ];
-	 *		const selection = new Selection( ranges, { backward } );
+	 *		const selection = new Selection( ranges );
 	 *
 	 *		// Creates selection from the other selection.
 	 *		// Note: It doesn't copies selection attributes.
@@ -56,18 +56,26 @@ export default class Selection {
 	 *		const position = new Position( root, path );
 	 *		const selection = new Selection( position );
 	 *
-	 * 		// Creates selection inside the given node.
+	 * 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 paragraph = writer.createElement( 'paragraph' );
-	 *		selection.setTo( paragraph, 'in', { backward } );
+	 *		const selection = new Selection( 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.
 	 *
-	 *		// Creates selection on the given node.
 	 *		const paragraph = writer.createElement( 'paragraph' );
-	 *		selection.setTo( paragraph, 'on', { backward } );
+	 *		const selection = new Selection( paragraph, 'on' );
 	 *
 	 * 		// Creates selection at the start position of the given element.
 	 *		const paragraph = writer.createElement( 'paragraph' );
 	 *		const selection = new Selection( paragraph, offset );
 	 *
+	 * `Selection`'s constructor allow passing additional options (`backward`) as the last argument.
+	 *
+	 * 		// Creates backward selection.
+	 *		const selection = new Selection( 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
@@ -311,13 +319,16 @@ export default class Selection {
 	 * {@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 null.
 	 *
+	 * 		// Removes all selection's ranges.
+	 *		selection.setTo( null );
+	 *
 	 *		// Sets selection to the given range.
 	 *		const range = new Range( start, end );
-	 *		selection.setTo( range, { backward } );
+	 *		selection.setTo( range );
 	 *
 	 *		// Sets selection to given ranges.
 	 * 		const ranges = [ new Range( start1, end2 ), new Range( star2, end2 ) ];
-	 *		selection.setTo( ranges, { backward } );
+	 *		selection.setTo( ranges );
 	 *
 	 *		// Sets selection to other selection.
 	 *		// Note: It doesn't copies selection attributes.
@@ -336,14 +347,19 @@ export default class Selection {
 	 * 		// Sets collapsed selection at the position of the given node and an offset.
 	 *		selection.setTo( paragraph, offset );
 	 *
-	 *		// Sets selection inside the given node.
-	 *		selection.setTo( paragraph, 'in', { backward } );
+	 * 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.
 	 *
-	 *		// Sets selection on the given node.
-	 *		selection.setTo( paragraph, 'on', { backward } );
+	 *		selection.setTo( paragraph, 'in' );
 	 *
-	 * 		// Removes all selection's ranges.
-	 *		selection.setTo( null );
+	 * Creates a range on an {@link module:engine/model/item~Item item} which starts before the item and ends just after the item.
+	 *
+	 *		selection.setTo( paragraph, 'on' );
+	 *
+	 * `Selection#setTo()`' method allow passing additional options (`backward`) as the last argument.
+	 *
+	 * 		// Sets backward selection.
+	 *		const selection = new Selection( range, { backward: true } );
 	 *
 	 * @param {module:engine/model/selection~Selection|module:engine/model/documentselection~DocumentSelection|
 	 * module:engine/model/position~Position|module:engine/model/node~Node|

src/model/writer.js

@@ -907,11 +907,11 @@ export default class Writer {
 	 *
 	 *		// Sets selection to the given range.
 	 *		const range = new Range( start, end );
-	 *		writer.setSelection( range, { backward } );
+	 *		writer.setSelection( range );
 	 *
 	 *		// Sets selection to given ranges.
 	 * 		const ranges = [ new Range( start1, end2 ), new Range( star2, end2 ) ];
-	 *		writer.setSelection( range, { backward } );
+	 *		writer.setSelection( range );
 	 *
 	 *		// Sets selection to other selection.
 	 *		const otherSelection = new Selection();
@@ -928,15 +928,23 @@ export default class Writer {
 	 * 		// Sets collapsed selection at the position of the given node and an offset.
 	 *		writer.setSelection( paragraph, offset );
 	 *
-	 *		// Sets selection inside the given node.
-	 *		writer.setSelection( paragraph, 'in', { backward } );
+	 * 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.
 	 *
-	 *		// Sets selection on the given node.
-	 *		writer.setSelection( paragraph, 'on', { backward } );
+	 *		writer.setSelection( 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.
+	 *
+	 *		writer.setSelection( paragraph, 'on' );
 	 *
 	 * 		// Removes all selection's ranges.
 	 *		writer.setSelection( null );
 	 *
+	 * `Writer#setSelection()` allow passing additional options (`backward`) as the last argument.
+	 *
+	 * 		// Sets selection as backward.
+	 *		writer.setSelection( range, { backward: true } );
+	 *
 	 * Throws `writer-incorrect-use` error when the writer is used outside the `change()` block.
 	 *
 	 * @param {module:engine/model/selection~Selection|module:engine/model/documentselection~DocumentSelection|

src/view/selection.js

@@ -59,11 +59,14 @@ export default class Selection {
 	 *		const paragraph = writer.createElement( 'paragraph' );
 	 *		const selection = new Selection( paragraph, offset );
 	 *
-	 *		// Creates selection inside the item.
+	 * Creates a range inside an {@link module:engine/view/element~Element element} which starts before the first child of
+ 	 * that element and ends after the last child of that element.
+	 *
 	 *		const paragraph = writer.createElement( 'paragraph' );
 	 *		const selection = new Selection( paragraph, 'in' );
 	 *
-	 *		// Creates selection on the item.
+	 * Creates a range on an {@link module:engine/view/item~Item item} which starts before the item and ends just after the item.
+	 *
 	 *		const paragraph = writer.createElement( 'paragraph' );
 	 *		const selection = new Selection( paragraph, 'on' );
 	 *
@@ -438,10 +441,13 @@ export default class Selection {
 	 * 		// Sets collapsed selection at the position of given item and offset.
 	 *		selection.setTo( paragraph, offset );
 	 *
-	 *		// Sets selection inside the item.
+	 * Creates a range inside an {@link module:engine/view/element~Element element} which starts before the first child of
+ 	 * that element and ends after the last child of that element.
+	 *
 	 *		selection.setTo( paragraph, 'in' );
 	 *
-	 *		// Sets selection on the item.
+	 * Creates a range on an {@link module:engine/view/item~Item item} which starts before the item and ends just after the item.
+	 *
 	 *		selection.setTo( paragraph, 'on' );
 	 *
 	 * 		// Clears selection. Removes all ranges.
@@ -453,7 +459,7 @@ export default class Selection {
 	 *		selection.setTo( range, { backward: true } );
 	 *
 	 *		// Sets selection as fake.
-	 8		// Fake selection does not render as browser native selection over selected elements and is hidden to the user.
+	 *		// Fake selection does not render as browser native selection over selected elements and is hidden to the user.
 	 * 		// This way, no native selection UI artifacts are displayed to the user and selection over elements can be
 	 * 		// represented in other way, for example by applying proper CSS class.
 	 *		selection.setTo( range, { fake: true } );

src/view/writer.js

@@ -61,16 +61,19 @@ export default class Writer {
 	 * 		// Sets collapsed selection at the position of given item and offset.
 	 *		writer.setSelection( paragraph, offset );
 	 *
-	 *		// Sets selection inside the item.
-	 *		writer.setSelection( paragraph, 'in' );
+	 * Creates a range inside an {@link module:engine/view/element~Element element} which starts before the first child of
+ 	 * that element and ends after the last child of that element.
+	 *
+	 * 		writer.setSelection( paragraph, 'in' );
+	 *
+	 * Creates a range on the {@link module:engine/view/item~Item item} which starts before the item and ends just after the item.
 	 *
-	 *		// Sets selection on the item.
 	 *		writer.setSelection( paragraph, 'on' );
 	 *
 	 * 		// Removes all ranges.
 	 *		writer.setSelection( null );
 	 *
-	 *	`Writer#setSelection()` allow passing additional options (`backward`, `fake` and `label`) as the last argument.
+	 * `Writer#setSelection()` allow passing additional options (`backward`, `fake` and `label`) as the last argument.
 	 *
 	 *		// Sets selection as backward.
 	 *		writer.setSelection( range, { backward: true } );