Index: /CKEditor/branches/features/readonly/_samples/readonly.html
===================================================================
--- /CKEditor/branches/features/readonly/_samples/readonly.html	(revision 6750)
+++ /CKEditor/branches/features/readonly/_samples/readonly.html	(revision 6751)
@@ -1,3 +1,3 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+﻿<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 <!--
 Copyright (c) 2003-2011, CKSource - Frederico Knabben. All rights reserved.
@@ -21,20 +21,17 @@
 // its initialization.
 CKEDITOR.on( 'instanceReady', function( ev )
-{
-	// Show the editor name and description in the browser status bar.
-	document.getElementById( 'eMessage' ).innerHTML = '<p>Instance <code>' + ev.editor.name + '<\/code> loaded.<\/p>';
+	{
+		// Show this sample buttons.
+		 document.getElementById( 'eButtons' ).style.display = 'block';
+	});
 
-	// Show this sample buttons.
-	 document.getElementById( 'eButtons' ).style.display = 'block';
-});
-
-function toggleReadOnly( isReadOnly )
+function toggleReadOnly( makeEditable )
 {
 	// Get the editor instance that we want to interact with.
-	var oEditor = CKEDITOR.instances.editor1;
+	var editor = CKEDITOR.instances.editor1;
 
 	// Change the read-only state of editor.
 	// http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.editor.html#setReadOnly
-	oEditor.setReadOnly( isReadOnly );
+	editor.setReadOnly( makeEditable );
 }
 
@@ -45,5 +42,5 @@
 <body>
 	<h1 class="samples">
-		CKEditor Sample &mdash; Using CKEditor ReadOnly API
+		CKEditor Sample &mdash; Using CKEditor Read-Only API
 	</h1>
 	<div class="description">
@@ -51,5 +48,5 @@
 		This sample shows how to use the
 		<a class="samples" href="http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.editor.html#setReadOnly">set read-only</a>
-		API to put editor into an immutable state.
+		API to put editor into read-only state, so user's are not able to change its contents.
 	</p>
 	<p>
@@ -69,11 +66,11 @@
 	</div>
 	<form action="sample_posteddata.php" method="post">
-		<textarea class="ckeditor" id="editor1" name="editor1" cols="100" rows="10"><p>This is some <strong>sample text</strong>. You are using <a href="http://ckeditor.com/">CKEditor</a>.some</p></textarea>
-		<div id="eMessage">
-		</div>
-		<div id="eButtons" style="display: none">
-			<input onclick="toggleReadOnly( true );" type="button" value="Turn on read-only" />
-			<input onclick="toggleReadOnly();" type="button" value="Turn off read-only" />
-		</div>
+		<p>
+			<textarea class="ckeditor" id="editor1" name="editor1" cols="100" rows="10">&lt;p&gt;This is some &lt;strong&gt;sample text&lt;/strong&gt;. You are using &lt;a href="http://ckeditor.com/"&gt;CKEditor&lt;/a&gt;.&lt;/p&gt;</textarea>
+		</p>
+		<p id="eButtons" style="display: none">
+			<input onclick="toggleReadOnly();" type="button" value="Turn on read-only" />
+			<input onclick="toggleReadOnly( true );" type="button" value="Turn off read-only" />
+		</p>
 	</form>
 	<div id="footer">
Index: /CKEditor/branches/features/readonly/_source/core/editor.js
===================================================================
--- /CKEditor/branches/features/readonly/_source/core/editor.js	(revision 6750)
+++ /CKEditor/branches/features/readonly/_source/core/editor.js	(revision 6751)
@@ -162,10 +162,9 @@
 
 		/**
-		 * Immutable field indicate the read-only state of this editor.
+		 * Indicates the read-only state of this editor. This is a read-only property.
 		 * @name CKEDITOR.editor.prototype.readOnly
+		 * @type Boolean
+		 * @since 3.6
 		 * @see CKEDITOR.editor.prototype.setReadOnly
-		 * @type Boolean
-		 * @default CKEDITOR.config.readOnly
-		 * @since 3.6
 		 */
 		editor.readOnly = !!( editor.config.readOnly || editor.element.getAttribute( 'disabled' ) );
@@ -726,15 +725,21 @@
 
 		/**
-		 * Turn editor into read-only mode or restore it from read-only mode.
-		 * @param enable {Boolean}
+		 * Puts or restores the editor into read-only state. When in read-only,
+		 * the user is not able to change the editor contents, but still use
+		 * some editor features. This function sets the readOnly property of
+		 * the editor, firing the "readOnly" event.<br><br>
+		 * <strong>Note:</strong> the current editing area will be reloaded.
+		 * @param {Boolean} [makeEditable] Indicates that the editor must be
+		 *		restored from read-only mode, making it editable.
 		 * @since 3.6
-		 * <strong>Note:</strong> current editing block will be reloaded.
-		 */
-		setReadOnly : function( enable )
-		{
-			if ( this.readOnly != enable )
-			{
-				this.readOnly = !!enable;
-				// Reload current mode, then fire the event on editor.
+		 */
+		setReadOnly : function( makeEditable )
+		{
+			if ( this.readOnly != !makeEditable )
+			{
+				this.readOnly = !makeEditable;
+				
+				// Fire the readOnly event so the editor features can update
+				// their state accordingly.
 				this.fire( 'readOnly' );
 			}
@@ -869,7 +874,8 @@
 
 /**
- * Whether to start the editor in read-only mode, otherwise it depends on if "disabled" attribute is presented on the host &lt;textarea&gt;.
+ * If "true", makes the editor start in read-only state. Otherwise, it'll check
+ * if the linked &lt;textarea&gt; has the "disabled" attribute.
  * @name CKEDITOR.config.readOnly
- * @see CKEDITOR.editor.setReadOnly
+ * @see CKEDITOR.editor#setReadOnly
  * @type Boolean
  * @default false
