Parcourir la source

Fixed documentation in view DocumentSelection.

Szymon Kupś il y a 7 ans
Parent
commit
e572239eb1
1 fichiers modifiés avec 29 ajouts et 17 suppressions
  1. 29 17
      packages/ckeditor5-engine/src/view/documentselection.js

+ 29 - 17
packages/ckeditor5-engine/src/view/documentselection.js

@@ -14,7 +14,7 @@ import EmitterMixin from '@ckeditor/ckeditor5-utils/src/emittermixin';
 /**
 /**
  * Class representing document selection in tree view. It's instance is stored at
  * 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
  * {@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 by using {@link module:engine/view/view~View#change} method.
+ * it has read-only API and can be modified only by writer obtained from {@link module:engine/view/view~View#change} method.
  *
  *
  * Selection can consist of {@link module:engine/view/range~Range ranges}.
  * 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},
  * Selection's ranges can be obtained via {@link module:engine/view/documentselection~DocumentSelection#getRanges getRanges},
@@ -29,7 +29,7 @@ import EmitterMixin from '@ckeditor/ckeditor5-utils/src/emittermixin';
  */
  */
 export default class DocumentSelection {
 export default class DocumentSelection {
 	/**
 	/**
-	 * Creates new selection instance.
+	 * Creates new DocumentSelection instance.
 	 *
 	 *
 	 * 		// Creates empty selection without ranges.
 	 * 		// Creates empty selection without ranges.
 	 *		const selection = new DocumentSelection();
 	 *		const selection = new DocumentSelection();
@@ -91,7 +91,12 @@ export default class DocumentSelection {
 	 * @param {String} [options.label] Label for the fake selection.
 	 * @param {String} [options.label] Label for the fake selection.
 	 */
 	 */
 	constructor( selectable = null, placeOrOffset, options ) {
 	constructor( selectable = null, placeOrOffset, options ) {
-		// TODO: docs
+		/**
+		 * Selection is used internally (`DocumentSelection` is a proxy to that selection).
+		 *
+		 * @private
+		 * @member {module:engine/view/selection~Selection}
+		 */
 		this._selection = new Selection();
 		this._selection = new Selection();
 
 
 		// Delegate change event to be fired on DocumentSelection instance.
 		// Delegate change event to be fired on DocumentSelection instance.
@@ -257,10 +262,11 @@ export default class DocumentSelection {
 	}
 	}
 
 
 	/**
 	/**
-	 * Checks whether this selection is equal to given selection. Selections are equal if they have same directions,
+	 * 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.
 	 * same number of ranges and all ranges from one selection equal to a range from other selection.
 	 *
 	 *
-	 * @param {module:engine/model/selection~Selection} otherSelection Selection to compare with.
+	 * @param {module:engine/view/selection~Selection|module:engine/view/documentselection~DocumentSelection} otherSelection
+	 * Selection to compare with.
 	 * @returns {Boolean} `true` if selections are equal, `false` otherwise.
 	 * @returns {Boolean} `true` if selections are equal, `false` otherwise.
 	 */
 	 */
 	isEqual( otherSelection ) {
 	isEqual( otherSelection ) {
@@ -272,7 +278,8 @@ export default class DocumentSelection {
 	 * number of ranges, and all {@link module:engine/view/range~Range#getTrimmed trimmed} ranges from one selection are
 	 * number of ranges, and all {@link module:engine/view/range~Range#getTrimmed trimmed} ranges from one selection are
 	 * equal to any trimmed range from other selection.
 	 * equal to any trimmed range from other selection.
 	 *
 	 *
-	 * @param {module:engine/view/documentselection~DocumentSelection} otherSelection Selection to compare with.
+	 * @param {module:engine/view/selection~Selection|module:engine/view/documentselection~DocumentSelection} otherSelection
+	 * Selection to compare with.
 	 * @returns {Boolean} `true` if selections are similar, `false` otherwise.
 	 * @returns {Boolean} `true` if selections are similar, `false` otherwise.
 	 */
 	 */
 	isSimilar( otherSelection ) {
 	isSimilar( otherSelection ) {
@@ -281,45 +288,50 @@ export default class DocumentSelection {
 
 
 	/**
 	/**
 	 * Sets this selection's ranges and direction to the specified location based on the given
 	 * Sets this selection's ranges and direction to the specified location based on the given
-	 * {@link module:engine/view/documentselection~DocumentSelection selection}, {@link module:engine/view/position~Position position},
+	 * {@link module:engine/view/documentselection~DocumentSelection document selection},
+	 * {@link module:engine/view/selection~Selection selection}, {@link module:engine/view/position~Position position},
 	 * {@link module:engine/view/item~Item item}, {@link module:engine/view/range~Range range},
 	 * {@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.
 	 * an iterable of {@link module:engine/view/range~Range ranges} or null.
 	 *
 	 *
 	 *		// Sets selection to the given range.
 	 *		// Sets selection to the given range.
 	 *		const range = new Range( start, end );
 	 *		const range = new Range( start, end );
-	 *		selection._setTo( range );
+	 *		documentSelection._setTo( range );
 	 *
 	 *
 	 *		// Sets selection to given ranges.
 	 *		// Sets selection to given ranges.
 	 * 		const ranges = [ new Range( start1, end2 ), new Range( star2, end2 ) ];
 	 * 		const ranges = [ new Range( start1, end2 ), new Range( star2, end2 ) ];
-	 *		selection._setTo( range );
+	 *		documentSelection._setTo( range );
 	 *
 	 *
 	 *		// Sets selection to the other selection.
 	 *		// Sets selection to the other selection.
 	 *		const otherSelection = new Selection();
 	 *		const otherSelection = new Selection();
-	 *		selection._setTo( otherSelection );
+	 *		documentSelection._setTo( otherSelection );
+	 *
+	 *	 	// Sets selection to contents of DocumentSelection.
+	 *		const documentSelection = new DocumentSelection();
+	 *		documentSelection._setTo( documentSelection );
 	 *
 	 *
 	 * 		// Sets collapsed selection at the given position.
 	 * 		// Sets collapsed selection at the given position.
 	 *		const position = new Position( root, path );
 	 *		const position = new Position( root, path );
-	 *		selection._setTo( position );
+	 *		documentSelection._setTo( position );
 	 *
 	 *
 	 * 		// Sets collapsed selection at the position of given item and offset.
 	 * 		// Sets collapsed selection at the position of given item and offset.
-	 *		selection._setTo( paragraph, offset );
+	 *		documentSelection._setTo( paragraph, offset );
 	 *
 	 *
 	 * Creates a range inside an {@link module:engine/view/element~Element element} which starts before the first child of
 	 * 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.
 	 * that element and ends after the last child of that element.
 	 *
 	 *
-	 *		selection._setTo( paragraph, 'in' );
+	 *		documentSelection._setTo( paragraph, 'in' );
 	 *
 	 *
 	 * Creates a range on an {@link module:engine/view/item~Item item} which starts before the item and ends just after 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' );
+	 *		documentSelection._setTo( paragraph, 'on' );
 	 *
 	 *
 	 * 		// Clears selection. Removes all ranges.
 	 * 		// Clears selection. Removes all ranges.
-	 *		selection._setTo( null );
+	 *		documentSelection._setTo( null );
 	 *
 	 *
 	 * `Selection#_setTo()` method allow passing additional options (`backward`, `fake` and `label`) as the last argument.
 	 * `Selection#_setTo()` method allow passing additional options (`backward`, `fake` and `label`) as the last argument.
 	 *
 	 *
 	 *		// Sets selection as backward.
 	 *		// Sets selection as backward.
-	 *		selection._setTo( range, { backward: true } );
+	 *		documentSelection._setTo( range, { backward: true } );
 	 *
 	 *
 	 * 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
 	 * This way, no native selection UI artifacts are displayed to the user and selection over elements can be
@@ -329,7 +341,7 @@ export default class DocumentSelection {
 	 * (and be  properly handled by screen readers).
 	 * (and be  properly handled by screen readers).
 	 *
 	 *
 	 *		// Creates fake selection with label.
 	 *		// Creates fake selection with label.
-	 *		selection._setTo( range, { fake: true, label: 'foo' } );
+	 *		documentSelection._setTo( range, { fake: true, label: 'foo' } );
 	 *
 	 *
 	 * @protected
 	 * @protected
 	 * @fires change
 	 * @fires change