JasonWoof Got questions, comments, patches, etc.? Contact Jason Woofenden
vanilla ckeditor-3.6.1
[ckeditor.git] / _source / core / editor.js
index 9801bbe..ff17efb 100644 (file)
@@ -120,11 +120,11 @@ For licensing, see LICENSE.html or http://ckeditor.com/license
 \r
                /**\r
                 * The name of the skin used by this editor instance. The skin name can\r
-                * be set though the {@link CKEDITOR.config.skin} setting.\r
+                * be set through the <code>{@link CKEDITOR.config.skin}</code> setting.\r
                 * @name CKEDITOR.editor.prototype.skinName\r
                 * @type String\r
                 * @example\r
-                * alert( editor.skinName );  // "kama" (e.g.)\r
+                * alert( editor.skinName );  // E.g. "kama"\r
                 */\r
                editor.skinName = skinName;\r
 \r
@@ -133,7 +133,7 @@ For licensing, see LICENSE.html or http://ckeditor.com/license
                 * @name CKEDITOR.editor.prototype.skinPath\r
                 * @type String\r
                 * @example\r
-                * alert( editor.skinPath );  // "http://example.com/ckeditor/skins/kama/" (e.g.)\r
+                * alert( editor.skinPath );  // E.g. "http://example.com/ckeditor/skins/kama/"\r
                 */\r
                editor.skinPath = skinPath;\r
 \r
@@ -142,21 +142,21 @@ For licensing, see LICENSE.html or http://ckeditor.com/license
                 * @name CKEDITOR.editor.prototype.skinClass\r
                 * @type String\r
                 * @example\r
-                * alert( editor.skinClass );  // "cke_skin_kama" (e.g.)\r
+                * alert( editor.skinClass );  // E.g. "cke_skin_kama"\r
                 */\r
                editor.skinClass = 'cke_skin_' + skinName;\r
 \r
                /**\r
                 * The <a href="http://en.wikipedia.org/wiki/Tabbing_navigation">tabbing\r
                 * navigation</a> order that has been calculated for this editor\r
-                * instance. This can be set by the {@link CKEDITOR.config.tabIndex}\r
-                * setting or taken from the "tabindex" attribute of the\r
-                * {@link #element} associated to the editor.\r
+                * instance. This can be set by the <code>{@link CKEDITOR.config.tabIndex}</code>\r
+                * setting or taken from the <code>tabindex</code> attribute of the\r
+                * <code>{@link #element}</code> associated with the editor.\r
                 * @name CKEDITOR.editor.prototype.tabIndex\r
                 * @type Number\r
                 * @default 0 (zero)\r
                 * @example\r
-                * alert( editor.tabIndex );  // "0" (e.g.)\r
+                * alert( editor.tabIndex );  // E.g. "0"\r
                 */\r
                editor.tabIndex = editor.config.tabIndex || editor.element.getAttribute( 'tabindex' ) || 0;\r
 \r
@@ -182,21 +182,21 @@ For licensing, see LICENSE.html or http://ckeditor.com/license
                        {\r
                                /**\r
                                 * The code for the language resources that have been loaded\r
-                                * for the user internface elements of this editor instance.\r
+                                * for the user interface elements of this editor instance.\r
                                 * @name CKEDITOR.editor.prototype.langCode\r
                                 * @type String\r
                                 * @example\r
-                                * alert( editor.langCode );  // "en" (e.g.)\r
+                                * alert( editor.langCode );  // E.g. "en"\r
                                 */\r
                                editor.langCode = languageCode;\r
 \r
                                /**\r
-                                * An object holding all language strings used by the editor\r
+                                * An object that contains all language strings used by the editor\r
                                 * interface.\r
                                 * @name CKEDITOR.editor.prototype.lang\r
                                 * @type CKEDITOR.lang\r
                                 * @example\r
-                                * alert( editor.lang.bold );  // "Negrito" (e.g. if language is Portuguese)\r
+                                * alert( editor.lang.bold );  // E.g. "Negrito" (if the language is set to Portuguese)\r
                                 */\r
                                // As we'll be adding plugin specific entries that could come\r
                                // from different language code files, we need a copy of lang,\r
@@ -207,6 +207,8 @@ For licensing, see LICENSE.html or http://ckeditor.com/license
                                if ( CKEDITOR.env.gecko && CKEDITOR.env.version < 10900 && editor.lang.dir == 'rtl' )\r
                                        editor.lang.dir = 'ltr';\r
 \r
+                               editor.fire( 'langLoaded' );\r
+\r
                                var config = editor.config;\r
                                config.contentsLangDirection == 'ui' && ( config.contentsLangDirection = editor.lang.dir );\r
 \r
@@ -253,12 +255,12 @@ For licensing, see LICENSE.html or http://ckeditor.com/license
                                var languageFiles = [];\r
 \r
                                /**\r
-                                * And object holding references to all plugins used by this\r
-                                * editor istance.\r
+                                * An object that contains references to all plugins used by this\r
+                                * editor instance.\r
                                 * @name CKEDITOR.editor.prototype.plugins\r
                                 * @type Object\r
                                 * @example\r
-                                * alert( editor.plugins.dialog.path );  // "http://example.com/ckeditor/plugins/dialog/" (e.g.)\r
+                                * alert( editor.plugins.dialog.path );  // E.g. "http://example.com/ckeditor/plugins/dialog/"\r
                                 */\r
                                editor.plugins = plugins;\r
 \r
@@ -347,7 +349,7 @@ For licensing, see LICENSE.html or http://ckeditor.com/license
                                 * @name CKEDITOR.editor.prototype.theme\r
                                 * @type CKEDITOR.theme\r
                                 * @example\r
-                                * alert( editor.theme );  "http://example.com/ckeditor/themes/default/" (e.g.)\r
+                                * alert( editor.theme );  // E.g. "http://example.com/ckeditor/themes/default/"\r
                                 */\r
                                var editorTheme = editor.theme = CKEDITOR.themes.get( theme );\r
                                editorTheme.path = CKEDITOR.themes.getPath( theme );\r
@@ -422,7 +424,7 @@ For licensing, see LICENSE.html or http://ckeditor.com/license
 \r
        /**\r
         * Initializes the editor instance. This function is called by the editor\r
-        * contructor (editor_basic.js).\r
+        * contructor (<code>editor_basic.js</code>).\r
         * @private\r
         */\r
        CKEDITOR.editor.prototype._init = function()\r
@@ -438,24 +440,25 @@ For licensing, see LICENSE.html or http://ckeditor.com/license
                        this._.styles = [];\r
 \r
                        /**\r
-                        * The DOM element that has been replaced by this editor instance. This\r
-                        * element holds the editor data on load and post.\r
+                        * The DOM element that was replaced by this editor instance. This\r
+                        * element stores the editor data on load and post.\r
                         * @name CKEDITOR.editor.prototype.element\r
                         * @type CKEDITOR.dom.element\r
                         * @example\r
                         * var editor = CKEDITOR.instances.editor1;\r
-                        * alert( <b>editor.element</b>.getName() );  "textarea"\r
+                        * alert( <strong>editor.element</strong>.getName() );  // E.g. "textarea"\r
                         */\r
                        this.element = element;\r
 \r
                        /**\r
-                        * The editor instance name. It hay be the replaced element id, name or\r
-                        * a default name using a progressive counter (editor1, editor2, ...).\r
+                        * The editor instance name. It may be the replaced element ID, name, or\r
+                        * a default name using the progressive counter (<code>editor1</code>,\r
+                        * <code>editor2</code>, ...).\r
                         * @name CKEDITOR.editor.prototype.name\r
                         * @type String\r
                         * @example\r
                         * var editor = CKEDITOR.instances.editor1;\r
-                        * alert( <b>editor.name</b> );  "editor1"\r
+                        * alert( <strong>editor.name</strong> );  // "editor1"\r
                         */\r
                        this.name = ( element && ( this.elementMode == CKEDITOR.ELEMENT_MODE_REPLACE )\r
                                                        && ( element.getId() || element.getNameAtt() ) )\r
@@ -465,7 +468,7 @@ For licensing, see LICENSE.html or http://ckeditor.com/license
                                throw '[CKEDITOR.editor] The instance "' + this.name + '" already exists.';\r
 \r
                        /**\r
-                        * A unique random string assigned to each editor instance in the page.\r
+                        * A unique random string assigned to each editor instance on the page.\r
                         * @name CKEDITOR.editor.prototype.id\r
                         * @type String\r
                         */\r
@@ -473,19 +476,19 @@ For licensing, see LICENSE.html or http://ckeditor.com/license
 \r
                        /**\r
                         * The configurations for this editor instance. It inherits all\r
-                        * settings defined in (@link CKEDITOR.config}, combined with settings\r
+                        * settings defined in <code>(@link CKEDITOR.config}</code>, combined with settings\r
                         * loaded from custom configuration files and those defined inline in\r
                         * the page when creating the editor.\r
                         * @name CKEDITOR.editor.prototype.config\r
                         * @type Object\r
                         * @example\r
                         * var editor = CKEDITOR.instances.editor1;\r
-                        * alert( <b>editor.config.theme</b> );  "default" e.g.\r
+                        * alert( <strong>editor.config.theme</strong> );  // E.g. "default"\r
                         */\r
                        this.config = CKEDITOR.tools.prototypedCopy( CKEDITOR.config );\r
 \r
                        /**\r
-                        * Namespace containing UI features related to this editor instance.\r
+                        * The namespace containing UI features related to this editor instance.\r
                         * @name CKEDITOR.editor.prototype.ui\r
                         * @type CKEDITOR.ui\r
                         * @example\r
@@ -495,7 +498,7 @@ For licensing, see LICENSE.html or http://ckeditor.com/license
                        /**\r
                         * Controls the focus state of this editor instance. This property\r
                         * is rarely used for normal API operations. It is mainly\r
-                        * destinated to developer adding UI elements to the editor interface.\r
+                        * intended for developers adding UI elements to the editor interface.\r
                         * @name CKEDITOR.editor.prototype.focusManager\r
                         * @type CKEDITOR.focusManager\r
                         * @example\r
@@ -516,7 +519,7 @@ CKEDITOR.tools.extend( CKEDITOR.editor.prototype,
        {\r
                /**\r
                 * Adds a command definition to the editor instance. Commands added with\r
-                * this function can be later executed with {@link #execCommand}.\r
+                * this function can be executed later with the <code>{@link #execCommand}</code> method.\r
                 * @param {String} commandName The indentifier name of the command.\r
                 * @param {CKEDITOR.commandDefinition} commandDefinition The command definition.\r
                 * @example\r
@@ -534,8 +537,9 @@ CKEDITOR.tools.extend( CKEDITOR.editor.prototype,
                },\r
 \r
                /**\r
-                * Add a trunk of css text to the editor which will be applied to the wysiwyg editing document.\r
-                * Note: This function should be called before editor is loaded to take effect.\r
+                * Adds a piece of CSS code to the editor which will be applied to the WYSIWYG editing document.\r
+                * This CSS would not be added to the output, and is there mainly for editor-specific editing requirements.\r
+                * Note: This function should be called before the editor is loaded to take effect.\r
                 * @param css {String} CSS text.\r
                 * @example\r
                 * editorInstance.addCss( 'body { background-color: grey; }' );\r
@@ -552,9 +556,9 @@ CKEDITOR.tools.extend( CKEDITOR.editor.prototype,
                 *              element, this parameter indicates whether or not to update the\r
                 *              element with the instance contents.\r
                 * @example\r
-                * alert( CKEDITOR.instances.editor1 );  e.g "object"\r
-                * <b>CKEDITOR.instances.editor1.destroy()</b>;\r
-                * alert( CKEDITOR.instances.editor1 );  "undefined"\r
+                * alert( CKEDITOR.instances.editor1 );  //  E.g "object"\r
+                * <strong>CKEDITOR.instances.editor1.destroy()</strong>;\r
+                * alert( CKEDITOR.instances.editor1 );  // "undefined"\r
                 */\r
                destroy : function( noUpdate )\r
                {\r
@@ -569,11 +573,12 @@ CKEDITOR.tools.extend( CKEDITOR.editor.prototype,
                },\r
 \r
                /**\r
-                * Executes a command.\r
+                * Executes a command associated with the editor.\r
                 * @param {String} commandName The indentifier name of the command.\r
-                * @param {Object} [data] Data to be passed to the command\r
-                * @returns {Boolean} "true" if the command has been successfuly\r
-                *              executed, otherwise "false".\r
+                * @param {Object} [data] Data to be passed to the command.\r
+                * @returns {Boolean} <code>true</code> if the command was executed\r
+                *              successfully, otherwise <code>false</code>.\r
+                * @see CKEDITOR.editor.addCommand\r
                 * @example\r
                 * editorInstance.execCommand( 'bold' );\r
                 */\r
@@ -605,12 +610,14 @@ CKEDITOR.tools.extend( CKEDITOR.editor.prototype,
                },\r
 \r
                /**\r
-                * Gets one of the registered commands. Note that, after registering a\r
-                * command definition with addCommand, it is transformed internally\r
-                * into an instance of {@link CKEDITOR.command}, which will be then\r
-                * returned by this function.\r
+                * Gets one of the registered commands. Note that after registering a\r
+                * command definition with <code>{@link #addCommand}</code>, it is\r
+                * transformed internally into an instance of\r
+                * <code>{@link CKEDITOR.command}</code>, which will then be returned\r
+                * by this function.\r
                 * @param {String} commandName The name of the command to be returned.\r
-                * This is the same used to register the command with addCommand.\r
+                * This is the same name that is used to register the command with\r
+                *              <code>addCommand</code>.\r
                 * @returns {CKEDITOR.command} The command object identified by the\r
                 * provided name.\r
                 */\r
@@ -625,7 +632,7 @@ CKEDITOR.tools.extend( CKEDITOR.editor.prototype,
                 * @type String\r
                 * @returns (String) The editor data.\r
                 * @example\r
-                * if ( CKEDITOR.instances.editor1.<b>getData()</b> == '' )\r
+                * if ( CKEDITOR.instances.editor1.<strong>getData()</strong> == '' )\r
                 *     alert( 'There is no data available' );\r
                 */\r
                getData : function()\r
@@ -653,11 +660,13 @@ CKEDITOR.tools.extend( CKEDITOR.editor.prototype,
 \r
                /**\r
                 * Gets the "raw data" currently available in the editor. This is a\r
-                * fast method which return the data as is, without processing, so it's\r
-                * not recommended to use it on resulting pages. It can be used instead\r
-                * combined with the {@link #loadSnapshot} so one can automatic save\r
-                * the editor data from time to time while the user is using the\r
-                * editor, to avoid data loss, without risking performance issues.\r
+                * fast method which returns the data as is, without processing, so it is\r
+                * not recommended to use it on resulting pages. Instead it can be used\r
+                * combined with the <code>{@link #loadSnapshot}</code> method in order\r
+                * to be able to automatically save the editor data from time to time\r
+                * while the user is using the editor, to avoid data loss, without risking\r
+                * performance issues.\r
+                * @see CKEDITOR.editor.getData\r
                 * @example\r
                 * alert( editor.getSnapshot() );\r
                 */\r
@@ -676,13 +685,14 @@ CKEDITOR.tools.extend( CKEDITOR.editor.prototype,
                },\r
 \r
                /**\r
-                * Loads "raw data" in the editor. This data is loaded with processing\r
+                * Loads "raw data" into the editor. The data is loaded with processing\r
                 * straight to the editing area. It should not be used as a way to load\r
                 * any kind of data, but instead in combination with\r
-                * {@link #getSnapshot} produced data.\r
+                * <code>{@link #getSnapshot}</code> produced data.\r
+                * @see CKEDITOR.editor.setData\r
                 * @example\r
                 * var data = editor.getSnapshot();\r
-                * editor.<b>loadSnapshot( data )</b>;\r
+                * editor.<strong>loadSnapshot( data )</strong>;\r
                 */\r
                loadSnapshot : function( snapshot )\r
                {\r
@@ -690,21 +700,22 @@ CKEDITOR.tools.extend( CKEDITOR.editor.prototype,
                },\r
 \r
                /**\r
-                * Sets the editor data. The data must be provided in raw format (HTML).<br />\r
+                * Sets the editor data. The data must be provided in the raw format (HTML).<br />\r
                 * <br />\r
-                * Note that this menthod is asynchronous. The "callback" parameter must\r
+                * Note that this method is asynchronous. The <code>callback</code> parameter must\r
                 * be used if interaction with the editor is needed after setting the data.\r
                 * @param {String} data HTML code to replace the curent content in the\r
                 *              editor.\r
-                * @param {Function} callback Function to be called after the setData\r
+                * @param {Function} callback Function to be called after the <code>setData</code>\r
                 *              is completed.\r
-                *@param {Boolean} internal Whether suppress  any event firing when copying data internally inside editor.\r
+                *@param {Boolean} internal Whether to suppress any event firing when copying data\r
+                *              internally inside the editor.\r
                 * @example\r
-                * CKEDITOR.instances.editor1.<b>setData</b>( '&lt;p&gt;This is the editor data.&lt;/p&gt;' );\r
+                * CKEDITOR.instances.editor1.<strong>setData</strong>( '&lt;p&gt;This is the editor data.&lt;/p&gt;' );\r
                 * @example\r
-                * CKEDITOR.instances.editor1.<b>setData</b>( '&lt;p&gt;Some other editor data.&lt;/p&gt;', function()\r
+                * CKEDITOR.instances.editor1.<strong>setData</strong>( '&lt;p&gt;Some other editor data.&lt;/p&gt;', function()\r
                 *     {\r
-                *         this.checkDirty();    // true\r
+                *         this.checkDirty();  // true\r
                 *     });\r
                 */\r
                setData : function( data , callback, internal )\r
@@ -729,19 +740,22 @@ CKEDITOR.tools.extend( CKEDITOR.editor.prototype,
 \r
                /**\r
                 * Puts or restores the editor into read-only state. When in read-only,\r
-                * the user is not able to change the editor contents, but still use\r
-                * some editor features. This function sets the readOnly property of\r
-                * the editor, firing the "readOnly" event.<br><br>\r
+                * the user is not able to change the editor contents, but can still use\r
+                * some editor features. This function sets the <code>{@link CKEDITOR.config.readOnly}</code>\r
+                * property of the editor, firing the <code>{@link CKEDITOR.editor#readOnly}</code> event.<br><br>\r
                 * <strong>Note:</strong> the current editing area will be reloaded.\r
-                * @param {Boolean} [makeEditable] Indicates that the editor must be\r
-                *              restored from read-only mode, making it editable.\r
+                * @param {Boolean} [isReadOnly] Indicates that the editor must go\r
+                *              read-only (<code>true</code>, default) or be restored and made editable\r
+                *              (<code>false</code>).\r
                 * @since 3.6\r
                 */\r
-               setReadOnly : function( makeEditable )\r
+               setReadOnly : function( isReadOnly )\r
                {\r
-                       if ( this.readOnly != !makeEditable )\r
+                       isReadOnly = ( isReadOnly == undefined ) || isReadOnly;\r
+\r
+                       if ( this.readOnly != isReadOnly )\r
                        {\r
-                               this.readOnly = !makeEditable;\r
+                               this.readOnly = isReadOnly;\r
 \r
                                // Fire the readOnly event so the editor features can update\r
                                // their state accordingly.\r
@@ -750,10 +764,10 @@ CKEDITOR.tools.extend( CKEDITOR.editor.prototype,
                },\r
 \r
                /**\r
-                * Inserts HTML into the currently selected position in the editor.\r
+                * Inserts HTML code into the currently selected position in the editor in WYSIWYG mode.\r
                 * @param {String} data HTML code to be inserted into the editor.\r
                 * @example\r
-                * CKEDITOR.instances.editor1.<b>insertHtml( '&lt;p&gt;This is a new paragraph.&lt;/p&gt;' )</b>;\r
+                * CKEDITOR.instances.editor1.<strong>insertHtml( '&lt;p&gt;This is a new paragraph.&lt;/p&gt;' )</strong>;\r
                 */\r
                insertHtml : function( data )\r
                {\r
@@ -762,14 +776,14 @@ CKEDITOR.tools.extend( CKEDITOR.editor.prototype,
 \r
                /**\r
                 * Insert text content into the currently selected position in the\r
-                * editor, in WYSIWYG mode, styles of the selected element will be applied to the inserted text,\r
-                * spaces around the text will be leaving untouched.\r
-                * <strong>Note:</strong> two subsequent line-breaks will introduce one paragraph, which element depends on {@link CKEDITOR.config.enterMode};\r
+                * editor in WYSIWYG mode. The styles of the selected element will be applied to the inserted text.\r
+                * Spaces around the text will be leaving untouched.\r
+                * <strong>Note:</strong> two subsequent line-breaks will introduce one paragraph. This depends on <code>{@link CKEDITOR.config.enterMode}</code>;\r
                 * A single line-break will be instead translated into one &lt;br /&gt;.\r
                 * @since 3.5\r
                 * @param {String} text Text to be inserted into the editor.\r
                 * @example\r
-                * CKEDITOR.instances.editor1.<b>insertText( ' line1 \n\n line2' )</b>;\r
+                * CKEDITOR.instances.editor1.<strong>insertText( ' line1 \n\n line2' )</strong>;\r
                 */\r
                insertText : function( text )\r
                {\r
@@ -778,12 +792,12 @@ CKEDITOR.tools.extend( CKEDITOR.editor.prototype,
 \r
                /**\r
                 * Inserts an element into the currently selected position in the\r
-                * editor.\r
+                * editor in WYSIWYG mode.\r
                 * @param {CKEDITOR.dom.element} element The element to be inserted\r
                 *              into the editor.\r
                 * @example\r
                 * var element = CKEDITOR.dom.element.createFromHtml( '&lt;img src="hello.png" border="0" title="Hello" /&gt;' );\r
-                * CKEDITOR.instances.editor1.<b>insertElement( element )</b>;\r
+                * CKEDITOR.instances.editor1.<strong>insertElement( element )</strong>;\r
                 */\r
                insertElement : function( element )\r
                {\r
@@ -791,16 +805,16 @@ CKEDITOR.tools.extend( CKEDITOR.editor.prototype,
                },\r
 \r
                /**\r
-                * Checks whether the current editor contents present changes when\r
+                * Checks whether the current editor contents contain changes when\r
                 * compared to the contents loaded into the editor at startup, or to\r
-                * the contents available in the editor when {@link #resetDirty} has\r
-                * been called.\r
-                * @returns {Boolean} "true" is the contents present changes.\r
+                * the contents available in the editor when <code>{@link #resetDirty}</code>\r
+                * was called.\r
+                * @returns {Boolean} "true" is the contents contain changes.\r
                 * @example\r
                 * function beforeUnload( e )\r
                 * {\r
-                *     if ( CKEDITOR.instances.editor1.<b>checkDirty()</b> )\r
-                *              return e.returnValue = "You'll loose the changes made in the editor.";\r
+                *     if ( CKEDITOR.instances.editor1.<strong>checkDirty()</strong> )\r
+                *              return e.returnValue = "You will lose the changes made in the editor.";\r
                 * }\r
                 *\r
                 * if ( window.addEventListener )\r
@@ -815,11 +829,11 @@ CKEDITOR.tools.extend( CKEDITOR.editor.prototype,
 \r
                /**\r
                 * Resets the "dirty state" of the editor so subsequent calls to\r
-                * {@link #checkDirty} will return "false" if the user will not make\r
-                * further changes to the contents.\r
+                * <code>{@link #checkDirty}</code> will return <code>false</code> if the user will not\r
+                * have made further changes to the contents.\r
                 * @example\r
-                * alert( editor.checkDirty() );  // "true" (e.g.)\r
-                * editor.<b>resetDirty()</b>;\r
+                * alert( editor.checkDirty() );  // E.g. "true"\r
+                * editor.<strong>resetDirty()</strong>;\r
                 * alert( editor.checkDirty() );  // "false"\r
                 */\r
                resetDirty : function()\r
@@ -829,8 +843,9 @@ CKEDITOR.tools.extend( CKEDITOR.editor.prototype,
                },\r
 \r
                /**\r
-                * Updates the &lt;textarea&gt; element that has been replaced by the editor with\r
+                * Updates the <code>&lt;textarea&gt;</code> element that was replaced by the editor with\r
                 * the current data available in the editor.\r
+                * @see CKEDITOR.editor.element\r
                 * @example\r
                 * CKEDITOR.instances.editor1.updateElement();\r
                 * alert( document.getElementById( 'editor1' ).value );  // The current editor data.\r
@@ -867,7 +882,7 @@ CKEDITOR.on( 'loaded', function()
        });\r
 \r
 /**\r
- * Whether escape HTML when editor update original input element.\r
+ * Whether to escape HTML when the editor updates the original input element.\r
  * @name CKEDITOR.config.htmlEncodeOutput\r
  * @since 3.1\r
  * @type Boolean\r
@@ -877,8 +892,8 @@ CKEDITOR.on( 'loaded', function()
  */\r
 \r
 /**\r
- * If "true", makes the editor start in read-only state. Otherwise, it'll check\r
- * if the linked &lt;textarea&gt; has the "disabled" attribute.\r
+ * If <code>true</code>, makes the editor start in read-only state. Otherwise, it will check\r
+ * if the linked <code>&lt;textarea&gt;</code> element has the <code>disabled</code> attribute.\r
  * @name CKEDITOR.config.readOnly\r
  * @see CKEDITOR.editor#setReadOnly\r
  * @type Boolean\r
@@ -891,7 +906,7 @@ CKEDITOR.on( 'loaded', function()
 /**\r
  * Fired when a CKEDITOR instance is created, but still before initializing it.\r
  * To interact with a fully initialized instance, use the\r
- * {@link CKEDITOR#instanceReady} event instead.\r
+ * <code>{@link CKEDITOR#instanceReady}</code> event instead.\r
  * @name CKEDITOR#instanceCreated\r
  * @event\r
  * @param {CKEDITOR.editor} editor The editor instance that has been created.\r
@@ -905,6 +920,14 @@ CKEDITOR.on( 'loaded', function()
  */\r
 \r
 /**\r
+ * Fired when the language is loaded into the editor instance.\r
+ * @name CKEDITOR.editor#langLoaded\r
+ * @event\r
+ * @since 3.6.1\r
+ * @param {CKEDITOR.editor} editor This editor instance.\r
+ */\r
+\r
+/**\r
  * Fired when all plugins are loaded and initialized into the editor instance.\r
  * @name CKEDITOR.editor#pluginsLoaded\r
  * @event\r
@@ -912,7 +935,7 @@ CKEDITOR.on( 'loaded', function()
  */\r
 \r
 /**\r
- * Fired before the command execution when {@link #execCommand} is called.\r
+ * Fired before the command execution when <code>{@link #execCommand}</code> is called.\r
  * @name CKEDITOR.editor#beforeCommandExec\r
  * @event\r
  * @param {CKEDITOR.editor} editor This editor instance.\r
@@ -923,7 +946,7 @@ CKEDITOR.on( 'loaded', function()
  */\r
 \r
 /**\r
- * Fired after the command execution when {@link #execCommand} is called.\r
+ * Fired after the command execution when <code>{@link #execCommand}</code> is called.\r
  * @name CKEDITOR.editor#afterCommandExec\r
  * @event\r
  * @param {CKEDITOR.editor} editor This editor instance.\r
@@ -934,16 +957,15 @@ CKEDITOR.on( 'loaded', function()
  */\r
 \r
 /**\r
- * Fired every custom configuration file is loaded, before the final\r
+ * Fired when the custom configuration file is loaded, before the final\r
  * configurations initialization.<br />\r
  * <br />\r
  * Custom configuration files can be loaded thorugh the\r
- * {@link CKEDITOR.config.customConfig} setting. Several files can be loading\r
- * by chaning this setting.\r
+ * <code>{@link CKEDITOR.config.customConfig}</code> setting. Several files can be loaded\r
+ * by changing this setting.\r
  * @name CKEDITOR.editor#customConfigLoaded\r
  * @event\r
  * @param {CKEDITOR.editor} editor This editor instance.\r
- * @example\r
  */\r
 \r
 /**\r
@@ -951,14 +973,11 @@ CKEDITOR.on( 'loaded', function()
  * @name CKEDITOR.editor#configLoaded\r
  * @event\r
  * @param {CKEDITOR.editor} editor This editor instance.\r
- * @example\r
- * if( editor.config.fullPage )\r
- *     alert( 'This is a full page editor' );\r
  */\r
 \r
 /**\r
  * Fired when this editor instance is destroyed. The editor at this\r
- * point isn't usable and this event should be used to perform clean up\r
+ * point is not usable and this event should be used to perform the clean-up\r
  * in any plugin.\r
  * @name CKEDITOR.editor#destroy\r
  * @event\r
@@ -971,20 +990,19 @@ CKEDITOR.on( 'loaded', function()
  */\r
 \r
 /**\r
- * Internal event to perform the #getSnapshot call.\r
+ * Internal event to perform the <code>#getSnapshot</code> call.\r
  * @name CKEDITOR.editor#getSnapshot\r
  * @event\r
  */\r
 \r
 /**\r
- * Internal event to perform the #loadSnapshot call.\r
+ * Internal event to perform the <code>#loadSnapshot</code> call.\r
  * @name CKEDITOR.editor#loadSnapshot\r
  * @event\r
  */\r
 \r
-\r
 /**\r
- * Event fired before the #getData call returns allowing additional manipulation.\r
+ * Event fired before the <code>#getData</code> call returns allowing additional manipulation.\r
  * @name CKEDITOR.editor#getData\r
  * @event\r
  * @param {CKEDITOR.editor} editor This editor instance.\r
@@ -992,7 +1010,7 @@ CKEDITOR.on( 'loaded', function()
  */\r
 \r
 /**\r
- * Event fired before the #setData call is executed allowing additional manipulation.\r
+ * Event fired before the <code>#setData</code> call is executed allowing additional manipulation.\r
  * @name CKEDITOR.editor#setData\r
  * @event\r
  * @param {CKEDITOR.editor} editor This editor instance.\r
@@ -1000,8 +1018,8 @@ CKEDITOR.on( 'loaded', function()
  */\r
 \r
 /**\r
- * Event fired at the end of the #setData call is executed. Usually it's better to use the\r
- * {@link CKEDITOR.editor.prototype.dataReady} event.\r
+ * Event fired at the end of the <code>#setData</code> call execution. Usually it is better to use the\r
+ * <code>{@link CKEDITOR.editor.prototype.dataReady}</code> event.\r
  * @name CKEDITOR.editor#afterSetData\r
  * @event\r
  * @param {CKEDITOR.editor} editor This editor instance.\r
@@ -1009,7 +1027,7 @@ CKEDITOR.on( 'loaded', function()
  */\r
 \r
 /**\r
- * Internal event to perform the #insertHtml call\r
+ * Internal event to perform the <code>#insertHtml</code> call\r
  * @name CKEDITOR.editor#insertHtml\r
  * @event\r
  * @param {CKEDITOR.editor} editor This editor instance.\r
@@ -1017,7 +1035,7 @@ CKEDITOR.on( 'loaded', function()
  */\r
 \r
 /**\r
- * Internal event to perform the #insertText call\r
+ * Internal event to perform the <code>#insertText</code> call\r
  * @name CKEDITOR.editor#insertText\r
  * @event\r
  * @param {CKEDITOR.editor} editor This editor instance.\r
@@ -1025,7 +1043,7 @@ CKEDITOR.on( 'loaded', function()
  */\r
 \r
 /**\r
- * Internal event to perform the #insertElement call\r
+ * Internal event to perform the <code>#insertElement</code> call\r
  * @name CKEDITOR.editor#insertElement\r
  * @event\r
  * @param {CKEDITOR.editor} editor This editor instance.\r
@@ -1033,7 +1051,7 @@ CKEDITOR.on( 'loaded', function()
  */\r
 \r
 /**\r
- * Event fired after {@link CKEDITOR.editor#readOnly} property changes.\r
+ * Event fired after the <code>{@link CKEDITOR.editor#readOnly}</code> property changes.\r
  * @name CKEDITOR.editor#readOnly\r
  * @event\r
  * @since 3.6\r