Index: /CKEditor/trunk/_source/core/dom/range.js
===================================================================
--- /CKEditor/trunk/_source/core/dom/range.js	(revision 5626)
+++ /CKEditor/trunk/_source/core/dom/range.js	(revision 5627)
@@ -1,3 +1,3 @@
-/*
+/*
 Copyright (c) 2003-2010, CKSource - Frederico Knabben. All rights reserved.
 For licensing, see LICENSE.html or http://ckeditor.com/license
@@ -698,5 +698,5 @@
 
 		/**
-		 * Move the range out of bookmark nodes if they're been the container.
+		 * Move the range out of bookmark nodes if they'd been the container.
 		 */
 		optimizeBookmark: function()
@@ -1167,11 +1167,11 @@
 					var walker = new CKEDITOR.dom.walker( walkerRange ),
 					    blockBoundary,  // The node on which the enlarging should stop.
-						tailBr, //
-					    defaultGuard = CKEDITOR.dom.walker.blockBoundary(
+						tailBr, // In case BR as block boundary.
+					    notBlockBoundary = CKEDITOR.dom.walker.blockBoundary(
 								( unit == CKEDITOR.ENLARGE_LIST_ITEM_CONTENTS ) ? { br : 1 } : null ),
 						// Record the encountered 'blockBoundary' for later use.
 						boundaryGuard = function( node )
 						{
-							var retval = defaultGuard( node );
+							var retval = notBlockBoundary( node );
 							if ( !retval )
 								blockBoundary = node;
@@ -1194,6 +1194,7 @@
 					blockBoundary = blockBoundary || body;
 
-					// Start the range at different position by comparing
-					// the document position of it with 'enlargeable' node.
+					// Start the range either after the end of found block (<p>...</p>[text)
+					// or at the start of block (<p>[text...), by comparing the document position
+					// with 'enlargeable' node.
 					this.setStartAt(
 							blockBoundary,
@@ -1221,6 +1222,6 @@
 					blockBoundary = blockBoundary || body;
 
-					// Start the range at different position by comparing
-					// the document position of it with 'enlargeable' node.
+					// Close the range either before the found block start (text]<p>...</p>) or at the block end (...text]</p>)
+					// by comparing the document position with 'enlargeable' node.
 					this.setEndAt(
 							blockBoundary,
@@ -1238,6 +1239,13 @@
 		/**
 		 *  Descrease the range to make sure that boundaries
-		 *  always anchor beside text nodes or innermost element.
+		*  always anchor beside text nodes or innermost element.
 		 * @param {Number} mode  ( CKEDITOR.SHRINK_ELEMENT | CKEDITOR.SHRINK_TEXT ) The shrinking mode.
+		 * <dl>
+		 * 	 <dt>CKEDITOR.SHRINK_ELEMENT</dt>
+		 * 	 <dd>Shrink the range boundaries to the edge of the innermost element.</dd>
+		 * 	 <dt>CKEDITOR.SHRINK_TEXT</dt>
+		 * 	 <dd>Shrink the range boudaries to anchor by the side of enclosed text  node, range remains if there's no text nodes on boundaries at all.</dd>
+		  * </dl>
+		 * @param {Boolean} selectContents Whether result range anchors at the inner OR outer boundary of the node.   
 		 */
 		shrink : function( mode, selectContents )
@@ -1639,10 +1647,10 @@
 			   : CKEDITOR.POSITION_BEFORE_END );
 
-			var walker = new CKEDITOR.dom.walker( walkerRange ),
-			 retval = false;
+			var walker = new CKEDITOR.dom.walker( walkerRange );
 			walker.evaluator = elementBoundaryEval;
 			return walker[ checkType == CKEDITOR.START ?
 				'checkBackward' : 'checkForward' ]();
 		},
+
 		// Calls to this function may produce changes to the DOM. The range may
 		// be updated to reflect such changes.
@@ -1792,5 +1800,5 @@
 			var walkerRange = this.clone();
 
-			// Optimize and analyze the range to avoid DOM destructive nature of walker. (#
+			// Optimize and analyze the range to avoid DOM destructive nature of walker. (#5780)
 			walkerRange.optimize();
 			if ( walkerRange.startContainer.type != CKEDITOR.NODE_ELEMENT
@@ -1844,5 +1852,5 @@
 /**
  * Check boundary types.
- * @see CKEDITOR.dom.range::checkBoundaryOfElement
+ * @see CKEDITOR.dom.range.prototype.checkBoundaryOfElement
  */
 CKEDITOR.START = 1;
@@ -1850,4 +1858,8 @@
 CKEDITOR.STARTEND = 3;
 
+/**
+ * Shrink range types.
+ * @see CKEDITOR.dom.range.prototype.shrink
+ */
 CKEDITOR.SHRINK_ELEMENT = 1;
 CKEDITOR.SHRINK_TEXT = 2;