From 42f0b8e425a5de85f6c65a3df3c8f9cbcb123ae3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Piotrek=20Koszuli=C5=84ski?= <pkoszulinski@gmail.com>
Date: Tue, 11 Jul 2017 17:47:38 +0200
Subject: [PATCH] Minor docs and code cleanup.

---
 src/model/position.js   |  6 +-----
 src/model/range.js      |  2 +-
 src/view/position.js    |  2 +-
 src/view/range.js       |  2 +-
 tests/model/position.js | 11 ++++++-----
 5 files changed, 10 insertions(+), 13 deletions(-)

diff --git a/src/model/position.js b/src/model/position.js
index bb97c7181..918ae55b3 100644
--- a/src/model/position.js
+++ b/src/model/position.js
@@ -320,16 +320,12 @@ export default class Position {
 
 	/**
 	 * Returns an {@link module:engine/model/element~Element} or {@link module:engine/model/documentfragment~DocumentFragment}
-	 * which is a common ancestor for both positions. The {@link #root roots} of these two positions must be identical.
+	 * which is a common ancestor of both positions. The {@link #root roots} of these two positions must be identical.
 	 *
 	 * @param {module:engine/model/position~Position} position The second position.
 	 * @returns {module:engine/model/element~Element|module:engine/model/documentfragment~DocumentFragment|null}
 	 */
 	getCommonAncestor( position ) {
-		if ( this.root !== position.root ) {
-			return null;
-		}
-
 		const ancestorsA = this.getAncestors();
 		const ancestorsB = position.getAncestors();
 
diff --git a/src/model/range.js b/src/model/range.js
index 7eb3fd9db..8fef4225d 100644
--- a/src/model/range.js
+++ b/src/model/range.js
@@ -447,7 +447,7 @@ export default class Range {
 
 	/**
 	 * Returns an {@link module:engine/model/element~Element} or {@link module:engine/model/documentfragment~DocumentFragment}
-	 * which is a common ancestor for both positions.
+	 * which is a common ancestor of the range's both ends (in which the entire range is contained).
 	 *
 	 * @returns {module:engine/model/element~Element|module:engine/model/documentfragment~DocumentFragment|null}
 	 */
diff --git a/src/view/position.js b/src/view/position.js
index 7e2105a41..92b50cbd7 100644
--- a/src/view/position.js
+++ b/src/view/position.js
@@ -177,7 +177,7 @@ export default class Position {
 
 	/**
 	 * Returns a {@link module:engine/view/node~Node} or {@link module:engine/view/documentfragment~DocumentFragment}
-	 * which is a common ancestor for both positions.
+	 * which is a common ancestor of both positions.
 	 *
 	 * @param {module:engine/view/position~Position} position
 	 * @returns {module:engine/view/node~Node|module:engine/view/documentfragment~DocumentFragment|null}
diff --git a/src/view/range.js b/src/view/range.js
index 5c78d81ef..660acce24 100644
--- a/src/view/range.js
+++ b/src/view/range.js
@@ -306,7 +306,7 @@ export default class Range {
 
 	/**
 	 * Returns a {@link module:engine/view/node~Node} or {@link module:engine/view/documentfragment~DocumentFragment}
-	 * which is a common ancestor for both positions.
+	 * which is a common ancestor of range's both ends (in which the entire range is contained).
 	 *
 	 * @returns {module:engine/view/node~Node|module:engine/view/documentfragment~DocumentFragment|null}
 	 */
diff --git a/tests/model/position.js b/tests/model/position.js
index 2d1be9c8a..1b5a23eb5 100644
--- a/tests/model/position.js
+++ b/tests/model/position.js
@@ -846,9 +846,9 @@ describe( 'Position', () => {
 	} );
 
 	describe( 'getCommonAncestor()', () => {
-		it( 'returns null when roots of the position are not the same', () => {
+		it( 'returns null when roots of both positions are not the same', () => {
 			const pos1 = new Position( root, [ 0 ] );
-			const pos2 = new Position( otherRoot, [ 1, 1 ] );
+			const pos2 = new Position( otherRoot, [ 0 ] );
 
 			test( pos1, pos2, null );
 		} );
@@ -887,11 +887,12 @@ describe( 'Position', () => {
 			test( liPosition, zPosition, ul );
 		} );
 
-		it( 'works if position is hooked before an empty element', () => {
+		// Checks if by mistake someone didn't use getCommonPath() + getNodeByPath().
+		it( 'works if position is located before an element', () => {
 			const doc = new Document();
 			const root = doc.createRoot();
 
-			const p = new Element( 'p', null, new Element( 'a', null, [] ) );
+			const p = new Element( 'p', null, new Element( 'a' ) );
 
 			root.appendChildren( p );
 
@@ -900,7 +901,7 @@ describe( 'Position', () => {
 			test( postion, postion, p );
 		} );
 
-		it( 'works fine with positions hooked in `DocumentFragment`', () => {
+		it( 'works fine with positions located in DocumentFragment', () => {
 			const docFrag = new DocumentFragment( [ p, ul ] );
 			const zPosition = new Position( docFrag, [ 1, 0, 2 ] );
 			const afterLiPosition = new Position( docFrag, [ 1, 2 ] );