From 9cbe464faa31d1358ac99383574e6b37ab477875 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Piotrek=20Reinmar=20Koszuli=C5=84ski?= Date: Tue, 14 Aug 2012 12:23:25 +0200 Subject: [PATCH] Docs reformatted: config.js, ckeditor.js, ckeditor_base.js, bootstrap.js, commanddefinition.js, command.js. --- ckeditor.js | 19 +-- core/_bootstrap.js | 2 +- core/ckeditor.js | 106 ++++++++------- core/ckeditor_base.js | 7 +- core/ckeditor_basic.js | 23 ++-- core/command.js | 183 +++++++++++++------------- core/commanddefinition.js | 165 +++++++++++------------- core/config.js | 262 +++++++++++++++++--------------------- core/editor.js | 61 +++++---- 9 files changed, 389 insertions(+), 439 deletions(-) diff --git a/ckeditor.js b/ckeditor.js index 7421321570c..6279fbceb71 100644 --- a/ckeditor.js +++ b/ckeditor.js @@ -28,14 +28,15 @@ else { /** * The skin to load for all created instances, it may be the name of the skin * folder inside the editor installation path, or the name and the path separated - * by a comma.
- *
- * Note: This is a global configuration that applies to all instances. - * @name CKEDITOR.skinName - * @type String - * @example - * CKEDITOR.skinName = 'kama'; - * @example - * CKEDITOR.skinName = 'myskin,/customstuff/myskin/'; + * by a comma. + * + * **Note:** This is a global configuration that applies to all instances. + * + * CKEDITOR.skinName = 'kama'; + * + * CKEDITOR.skinName = 'myskin,/customstuff/myskin/'; + * + * @cfg {String} [skinName='kama'] + * @member CKEDITOR */ CKEDITOR.skinName = 'kama'; diff --git a/core/_bootstrap.js b/core/_bootstrap.js index d0426767081..969867d94da 100644 --- a/core/_bootstrap.js +++ b/core/_bootstrap.js @@ -32,7 +32,7 @@ if ( CKEDITOR.env.hc ) CKEDITOR.env.cssClass += ' cke_hc'; - /* Initially hide UI spaces when relevant skins are loading, later restored by skin css. */ + // Initially hide UI spaces when relevant skins are loading, later restored by skin css. CKEDITOR.document.appendStyleText( '.cke{visibility:hidden;}' ); // Mark the editor as fully loaded. diff --git a/core/ckeditor.js b/core/ckeditor.js index 27592c6ad31..c73ecda13a0 100644 --- a/core/ckeditor.js +++ b/core/ckeditor.js @@ -8,6 +8,8 @@ * definition. */ +/** @class CKEDITOR */ + // Remove the CKEDITOR.loadFullCore reference defined on ckeditor_basic. delete CKEDITOR.loadFullCore; @@ -15,25 +17,27 @@ delete CKEDITOR.loadFullCore; * Holds references to all editor instances created. The name of the properties * in this object correspond to instance names, and their values contains the * {@link CKEDITOR.editor} object representing them. - * @type {Object} - * @example - * alert( CKEDITOR.instances.editor1.name ); // "editor1" + * + * alert( CKEDITOR.instances.editor1.name ); // 'editor1' + * + * @property {Object} */ CKEDITOR.instances = {}; /** * The document of the window holding the CKEDITOR object. - * @type {CKEDITOR.dom.document} - * @example - * alert( CKEDITOR.document.getBody().getName() ); // "body" + * + * alert( CKEDITOR.document.getBody().getName() ); // 'body' + * + * @property {CKEDITOR.dom.document} */ CKEDITOR.document = new CKEDITOR.dom.document( document ); /** * Adds an editor instance to the global {@link CKEDITOR} object. This function * is available for internal use mainly. + * * @param {CKEDITOR.editor} editor The editor instance to be added. - * @example */ CKEDITOR.add = function( editor ) { CKEDITOR.instances[ editor.name ] = editor; @@ -57,9 +61,10 @@ CKEDITOR.add = function( editor ) { /** * Removes an editor instance from the global {@link CKEDITOR} object. This function - * is available for internal use only. External code must use {@link CKEDITOR.editor.prototype.destroy}. + * is available for internal use only. External code must use {@link CKEDITOR.editor#destroy}. + * + * @private * @param {CKEDITOR.editor} editor The editor instance to be removed. - * @example */ CKEDITOR.remove = function( editor ) { delete CKEDITOR.instances[ editor.name ]; @@ -75,7 +80,7 @@ CKEDITOR.remove = function( editor ) { * * @param {String} name The name which identify one UI template. * @param {String} source The source string for constructing this template. - * @return {CKEDITOR.template} The created template instance. + * @returns {CKEDITOR.template} The created template instance. */ CKEDITOR.addTemplate = function( name, source ) { var tpl = tpls[ name ]; @@ -91,6 +96,7 @@ CKEDITOR.remove = function( editor ) { /** * Retrieve a defined template created with {@link CKEDITOR.addTemplate}. + * * @param {String} name The template name. */ CKEDITOR.getTemplate = function( name ) { @@ -105,32 +111,32 @@ CKEDITOR.remove = function( editor ) { * Append a trunk of css to be appended to the editor document. * This method is mostly used by plugins to add custom styles to the editor * document. For basic contents styling the contents.css file should be - * used instead.

- * Note: This function should be called before the - * creation of editor instances. + * used instead. + * + * **Note:** This function should be called before the creation of editor instances. + * + * // Add styles for all headings inside of editable contents. + * CKEDITOR.addCss( '.cke_editable h1,.cke_editable h2,.cke_editable h3 { border-bottom: 1px dotted red }' ); + * + * @param {String} css The style rules to be appended. * @see CKEDITOR.config.contentsCss - * @param css {String} The style rules to be appended. - * @example - * // Add styles for all headings inside of editable contents. - * CKEDITOR.addCss( '.cke_editable h1,.cke_editable h2,.cke_editable h3 { border-bottom: 1px dotted red }' ); */ CKEDITOR.addCss = function( css ) { styles.push( css ); }; /** - * Returns a string will all CSS rules passes to the {@link CKEDITOR.addCss} method. - * @return {String} A string containing CSS rules. + * Returns a string will all CSS rules passes to the {@link CKEDITOR#addCss} method. + * + * @returns {String} A string containing CSS rules. */ CKEDITOR.getCss = function() { return styles.join( '\n' ); }; })(); -/** - * Perform global clean up to free as much memory as possible - * when there are no instances left - */ +// Perform global clean up to free as much memory as possible +// when there are no instances left CKEDITOR.on( 'instanceDestroyed', function() { if ( CKEDITOR.tools.isEmpty( this.instances ) ) CKEDITOR.fire( 'reset' ); @@ -142,55 +148,57 @@ CKEDITOR.loader.load( '_bootstrap' ); // %REMOVE_LINE% // Tri-state constants. /** * Used to indicate the ON or ACTIVE state. - * @constant - * @example + * + * @readonly + * @property {Number} [=1] */ CKEDITOR.TRISTATE_ON = 1; /** * Used to indicate the OFF or NON ACTIVE state. - * @constant - * @example + * + * @readonly + * @property {Number} [=2] */ CKEDITOR.TRISTATE_OFF = 2; /** * Used to indicate DISABLED state. - * @constant - * @example + * + * @readonly + * @property {Number} [=0] */ CKEDITOR.TRISTATE_DISABLED = 0; /** * The editor which is currently active (have user focus). - * @name CKEDITOR.currentInstance - * @type CKEDITOR.editor - * @see CKEDITOR#currentInstance - * @example - * function showCurrentEditorName() - * { - * if ( CKEDITOR.currentInstance ) - * alert( CKEDITOR.currentInstance.name ); - * else - * alert( 'Please focus an editor first.' ); - * } + * + * function showCurrentEditorName() { + * if ( CKEDITOR.currentInstance ) + * alert( CKEDITOR.currentInstance.name ); + * else + * alert( 'Please focus an editor first.' ); + * } + * + * @property {CKEDITOR.editor} currentInstance + * @see CKEDITOR#event-currentInstance */ /** * Fired when the CKEDITOR.currentInstance object reference changes. This may * happen when setting the focus on different editor instances in the page. - * @name CKEDITOR#currentInstance - * @event - * var editor; // Variable to hold a reference to the current editor. - * CKEDITOR.on( 'currentInstance' , function( e ) - * { - * editor = CKEDITOR.currentInstance; - * }); + * + * var editor; // Variable to hold a reference to the current editor. + * CKEDITOR.on( 'currentInstance', function() { + * editor = CKEDITOR.currentInstance; + * } ); + * + * @event currentInstance */ /** * Fired when the last instance has been destroyed. This event is used to perform * global memory clean up. - * @name CKEDITOR#reset - * @event + * + * @event reset */ diff --git a/core/ckeditor_base.js b/core/ckeditor_base.js index 99d50f5f90c..84bb52a7cea 100644 --- a/core/ckeditor_base.js +++ b/core/ckeditor_base.js @@ -64,7 +64,9 @@ if ( !window.CKEDITOR ) { /** * A 3-digit random integer, valid for the entire life of the CKEDITOR object. * - * alert( CKEDITOR.rnd ); // e.g. '319' + * alert( CKEDITOR.rnd ); // e.g. 319 + * + * @property {Number} */ rnd: Math.floor( Math.random() * ( 999 /*Max*/ - 100 /*Min*/ + 1 ) ) + 100 /*Min*/, @@ -72,6 +74,7 @@ if ( !window.CKEDITOR ) { * Private object used to hold core stuff. It should not be used outside of * the API code as properties defined here may change at any time * without notice. + * * @private */ _: { @@ -105,7 +108,7 @@ if ( !window.CKEDITOR ) { * global variable named ```CKEDITOR_BASEPATH```. This global variable * must be set **before** the editor script loading. * - * alert( CKEDITOR.basePath ); // "http://www.example.com/ckeditor/" (e.g.) + * alert( CKEDITOR.basePath ); // 'http://www.example.com/ckeditor/' (e.g.) * * @property {String} */ diff --git a/core/ckeditor_basic.js b/core/ckeditor_basic.js index a247c19dfed..cc3480e9d14 100644 --- a/core/ckeditor_basic.js +++ b/core/ckeditor_basic.js @@ -15,12 +15,14 @@ if ( CKEDITOR.status == 'unloaded' ) { /** * Forces the full CKEditor core code, in the case only the basic code has been - * loaded (ckeditor_basic.js). This method self-destroys (becomes undefined) in + * loaded (```ckeditor_basic.js```). This method self-destroys (becomes undefined) in * the first call or as soon as the full code is available. - * @example - * // Check if the full core code has been loaded and load it. - * if ( CKEDITOR.loadFullCore ) - * CKEDITOR.loadFullCore(); + * + * // Check if the full core code has been loaded and load it. + * if ( CKEDITOR.loadFullCore ) + * CKEDITOR.loadFullCore(); + * + * @member CKEDITOR */ CKEDITOR.loadFullCore = function() { // If the basic code is not ready, just mark it to be loaded. @@ -47,11 +49,12 @@ if ( CKEDITOR.status == 'unloaded' ) { * editor is loaded on demand, as soon as an instance is created. * * This value must be set on the page before the page load completion. - * @type Number - * @default 0 (zero) - * @example - * // Loads the full source after five seconds. - * CKEDITOR.loadFullCoreTimeout = 5; + * + * // Loads the full source after five seconds. + * CKEDITOR.loadFullCoreTimeout = 5; + * + * @property + * @member CKEDITOR */ CKEDITOR.loadFullCoreTimeout = 0; diff --git a/core/command.js b/core/command.js index 12a30e624c0..7232f31d518 100644 --- a/core/command.js +++ b/core/command.js @@ -4,41 +4,39 @@ */ /** - * Creates a command class instance. - * @class Represents a command that can be executed on an editor instance. + * @class CKEDITOR.command Represents a command that can be executed on an editor instance. + * @mixins CKEDITOR.event + * @constructor Creates a command class instance. + * + * var command = new CKEDITOR.command( editor, { + * exec: function( editor ) { + * alert( editor.document.getBody().getHtml() ); + * } + * } ); + * * @param {CKEDITOR.editor} editor The editor instance this command will be - * related to. + * related to. * @param {CKEDITOR.commandDefinition} commandDefinition The command - * definition. - * @augments CKEDITOR.event - * @example - * var command = new CKEDITOR.command( editor, - * { - * exec : function( editor ) - * { - * alert( editor.document.getBody().getHtml() ); - * } - * }); + * definition. */ CKEDITOR.command = function( editor, commandDefinition ) { /** * Lists UI items that are associated to this command. This list can be * used to interact with the UI on command execution (by the execution code * itself, for example). - * @type Array - * @example - * alert( 'Number of UI items associated to this command: ' + command.uiItems.length ); + * + * alert( 'Number of UI items associated to this command: ' + command.uiItems.length ); */ this.uiItems = []; /** * Executes the command. + * + * command.exec(); // The command gets executed. + * * @param {Object} [data] Any data to pass to the command. Depends on the - * command implementation and requirements. - * @returns {Boolean} A boolean indicating that the command has been - * successfully executed. - * @example - * command.exec(); // The command gets executed. + * command implementation and requirements. + * @returns {Boolean} A boolean indicating that the command has been successfully executed. */ this.exec = function( data ) { if ( this.state == CKEDITOR.TRISTATE_DISABLED ) @@ -54,9 +52,11 @@ CKEDITOR.command = function( editor, commandDefinition ) { }; /** - * Explicitly update the status of the command, by firing the {@link CKEDITOR.command#event:refresh} event, - * as well as invoke the {@link CKEDITOR.commandDefinition.prototype.refresh} method if defined, this method + * Explicitly update the status of the command, by firing the {@link CKEDITOR.command#event-refresh} event, + * as well as invoke the {@link CKEDITOR.command#method-refresh} method if defined, this method * is to allow different parts of the editor code to contribute in command status resolution. + * + * @todo */ this.refresh = function( editor, path ) { // Do nothing is we're on read-only and this command doesn't support it. @@ -80,66 +80,58 @@ CKEDITOR.command = function( editor, commandDefinition ) { return ( commandDefinition.refresh && commandDefinition.refresh.apply( this, arguments ) !== false ); }; - CKEDITOR.tools.extend( this, commandDefinition, - // Defaults - /** @lends CKEDITOR.command.prototype */ - { + CKEDITOR.tools.extend( this, commandDefinition, { /** * The editor modes within which the command can be executed. The * execution will have no action if the current mode is not listed * in this property. - * @type Object - * @default { wysiwyg:1 } - * @see CKEDITOR.editor.prototype.mode - * @example - * // Enable the command in both WYSIWYG and Source modes. - * command.modes = { wysiwyg:1,source:1 }; - * @example - * // Enable the command in Source mode only. - * command.modes = { source:1 }; + * + * // Enable the command in both WYSIWYG and Source modes. + * command.modes = { wysiwyg:1,source:1 }; + * + * // Enable the command in Source mode only. + * command.modes = { source:1 }; + * + * @see CKEDITOR.editor#mode */ modes: { wysiwyg:1 }, /** * Indicates that the editor will get the focus before executing * the command. - * @type Boolean - * @default true - * @example - * // Do not force the editor to have focus when executing the command. - * command.editorFocus = false; + * + * // Do not force the editor to have focus when executing the command. + * command.editorFocus = false; + * + * @property {Boolean} [=true] */ editorFocus: 1, /** * Indicates that this command is sensible to the selection context. - * If "true", the {@link CKEDITOR.command.refresh} method will be + * If ```true```, the {@link CKEDITOR.command#method-refresh} method will be * called for this command on the {@link CKEDITOR.editor#selectionChange} event. - * @type Boolean - * @default false + * + * @property {Boolean} [=false] */ contextSensitive: !!commandDefinition.context, /** * Indicates the editor state. Possible values are: - * - * Do not set this property directly, using the {@link #setState} - * method instead. - * @type Number - * @default {@link CKEDITOR.TRISTATE_OFF} - * @example - * if ( command.state == CKEDITOR.TRISTATE_DISABLED ) - * alert( 'This command is disabled' ); + * + * * {@link CKEDITOR#TRISTATE_DISABLED}: the command is + * disabled. It's execution will have no effect. Same as {@link #disable}. + * * {@link CKEDITOR#TRISTATE_ON}: the command is enabled + * and currently active in the editor (for context sensitive commands, for example). + * * {@link CKEDITOR#TRISTATE_OFF}: the command is enabled + * and currently inactive in the editor (for context sensitive commands, for example). + * + * Do not set this property directly, using the {@link #setState} method instead. + * + * if ( command.state == CKEDITOR.TRISTATE_DISABLED ) + * alert( 'This command is disabled' ); + * + * @property {Number} [=CKEDITOR.TRISTATE_OFF] */ state: CKEDITOR.TRISTATE_OFF }); @@ -151,11 +143,10 @@ CKEDITOR.command = function( editor, commandDefinition ) { CKEDITOR.command.prototype = { /** * Enables the command for execution. The command state (see - * {@link CKEDITOR.command.prototype.state}) available before disabling it - * is restored. - * @example - * command.enable(); - * command.exec(); // Execute the command. + * {@link CKEDITOR.command#state}) available before disabling it is restored. + * + * command.enable(); + * command.exec(); // Execute the command. */ enable: function() { if ( this.state == CKEDITOR.TRISTATE_DISABLED ) @@ -164,11 +155,10 @@ CKEDITOR.command.prototype = { /** * Disables the command for execution. The command state (see - * {@link CKEDITOR.command.prototype.state}) will be set to - * {@link CKEDITOR.TRISTATE_DISABLED}. - * @example - * command.disable(); - * command.exec(); // "false" - Nothing happens. + * {@link CKEDITOR.command#state}) will be set to {@link CKEDITOR#TRISTATE_DISABLED}. + * + * command.disable(); + * command.exec(); // "false" - Nothing happens. */ disable: function() { this.setState( CKEDITOR.TRISTATE_DISABLED ); @@ -176,15 +166,16 @@ CKEDITOR.command.prototype = { /** * Sets the command state. + * + * command.setState( CKEDITOR.TRISTATE_ON ); + * command.exec(); // Execute the command. + * command.setState( CKEDITOR.TRISTATE_DISABLED ); + * command.exec(); // "false" - Nothing happens. + * command.setState( CKEDITOR.TRISTATE_OFF ); + * command.exec(); // Execute the command. + * * @param {Number} newState The new state. See {@link #state}. - * @returns {Boolean} Returns "true" if the command state changed. - * @example - * command.setState( CKEDITOR.TRISTATE_ON ); - * command.exec(); // Execute the command. - * command.setState( CKEDITOR.TRISTATE_DISABLED ); - * command.exec(); // "false" - Nothing happens. - * command.setState( CKEDITOR.TRISTATE_OFF ); - * command.exec(); // Execute the command. + * @returns {Boolean} Returns ```true``` if the command state changed. */ setState: function( newState ) { // Do nothing if there is no state change. @@ -206,8 +197,8 @@ CKEDITOR.command.prototype = { /** * Toggles the on/off (active/inactive) state of the command. This is * mainly used internally by context sensitive commands. - * @example - * command.toggleState(); + * + * command.toggleState(); */ toggleState: function() { if ( this.state == CKEDITOR.TRISTATE_OFF ) @@ -221,21 +212,25 @@ CKEDITOR.event.implementOn( CKEDITOR.command.prototype, true ); /** * Indicates the previous command state. - * @name CKEDITOR.command.prototype.previousState - * @type Number + * + * alert( command.previousState ); + * + * @property {Number} previousState * @see #state - * @example - * alert( command.previousState ); */ /** * Fired when the command state changes. - * @name CKEDITOR.command#state - * @event - * @example - * command.on( 'state' , function( e ) - * { - * // Alerts the new state. - * alert( this.state ); - * }); + * + * command.on( 'state', function( e ) { + * // Alerts the new state. + * alert( this.state ); + * } ); + * + * @event state + */ + + /** + * @event refresh + * @todo */ diff --git a/core/commanddefinition.js b/core/commanddefinition.js index da948c59195..3beaf74112b 100644 --- a/core/commanddefinition.js +++ b/core/commanddefinition.js @@ -10,141 +10,118 @@ */ /** - * (Virtual Class) Do not call this constructor. This class is not really part - * of the API. - * @name CKEDITOR.commandDefinition - * @class Virtual class that illustrates the features of command objects to be - * passed to the {@link CKEDITOR.editor.prototype.addCommand} function. - * @example + * Virtual class that illustrates the features of command objects to be + * passed to the {@link CKEDITOR.editor#addCommand} function. + * + * @class CKEDITOR.commandDefinition + * @abstract */ /** * The function to be fired when the commend is executed. - * @name CKEDITOR.commandDefinition.prototype.exec - * @function + * + * editorInstance.addCommand( 'sample', { + * exec: function( editor ) { + * alert( 'Executing a command for the editor name "' + editor.name + '"!' ); + * } + * } ); + * + * @method exec * @param {CKEDITOR.editor} editor The editor within which run the command. * @param {Object} [data] Additional data to be used to execute the command. * @returns {Boolean} Whether the command has been successfully executed. - * Defaults to "true", if nothing is returned. - * @example - * editorInstance.addCommand( 'sample', - * { - * exec : function( editor ) - * { - * alert( 'Executing a command for the editor name "' + editor.name + '"!' ); - * } - * }); + * Defaults to ```true```, if nothing is returned. */ /** * Whether the command need to be hooked into the redo/undo system. - * @name CKEDITOR.commandDefinition.prototype.canUndo - * @type {Boolean} - * @default true - * @field - * @example - * editorInstance.addCommand( 'alertName', - * { - * exec : function( editor ) - * { - * alert( editor.name ); - * }, - * canUndo : false // No support for undo/redo - * }); + * + * editorInstance.addCommand( 'alertName', { + * exec: function( editor ) { + * alert( editor.name ); + * }, + * canUndo: false // No support for undo/redo. + * } ); + * + * @property {Boolean} [canUndo=true] */ /** * Whether the command is asynchronous, which means that the - * {@link CKEDITOR.editor#event:afterCommandExec} event will be fired by the + * {@link CKEDITOR.editor#event-afterCommandExec} event will be fired by the * command itself manually, and that the return value of this command is not to - * be returned by the {@link CKEDITOR.command#exec} function. - * @name CKEDITOR.commandDefinition.prototype.async - * @default false - * @type {Boolean} - * @example - * editorInstance.addCommand( 'loadOptions', - * { - * exec : function( editor ) - * { - * // Asynchronous operation below. - * CKEDITOR.ajax.loadXml( 'data.xml', function() - * { - * editor.fire( 'afterCommandExec' ); - * )); - * }, - * async : true // The command need some time to complete after exec function returns. - * }); + * be returned by the {@link #exec} function. + * + * editorInstance.addCommand( 'loadOptions', { + * exec: function( editor ) { + * // Asynchronous operation below. + * CKEDITOR.ajax.loadXml( 'data.xml', function() { + * editor.fire( 'afterCommandExec' ); + * } ); + * }, + * async: true // The command need some time to complete after exec function returns. + * } ); + * + * @property {Boolean} [async=false] */ /** * Whether the command should give focus to the editor before execution. - * @name CKEDITOR.commandDefinition.prototype.editorFocus - * @type {Boolean} - * @default true + * + * editorInstance.addCommand( 'maximize', { + * exec: function( editor ) { + * // ... + * }, + * editorFocus: false // The command doesn't require focusing the editing document. + * } ); + * + * @property {Boolean} [editorFocus=true] * @see CKEDITOR.command#editorFocus - * @example - * editorInstance.addCommand( 'maximize', - * { - * exec : function( editor ) - * { - * // ... - * }, - * editorFocus : false // The command doesn't require focusing the editing document. - * }); */ /** - * Whether the command state should be set to {@link CKEDITOR.TRISTATE_DISABLED} on startup. - * @name CKEDITOR.commandDefinition.prototype.startDisabled - * @type {Boolean} - * @default false - * @example - * editorInstance.addCommand( 'unlink', - * { - * exec : function( editor ) - * { - * // ... - * }, - * startDisabled : true // Command is unavailable until selection is inside a link. - * }); + * Whether the command state should be set to {@link CKEDITOR#TRISTATE_DISABLED} on startup. + * + * editorInstance.addCommand( 'unlink', { + * exec: function( editor ) { + * // ... + * }, + * startDisabled: true // Command is unavailable until selection is inside a link. + * } ); + * + * @property {Boolean} [startDisabled=false] */ /** * Indicates that this command is sensible to the selection context. - * If "true", the {@link CKEDITOR.command.refresh} method will be + * If ```true```, the {@link CKEDITOR.command#method-refresh} method will be * called for this command on selection changes, with a single parameter * representing the current elements path. - * @name CKEDITOR.commandDefinition.prototype.contextSensitive - * @type Boolean - * @default true + * + * @property {Boolean} [contextSensitive=true] */ /** * Sets the element name used to reflect the command state on selection changes. * If the selection is in a place where the element is not allowed, the command * will be disabled. - * Setting this property overrides - * {@link CKEDITOR.commandDefinition.prototype.contextSensitive} to "true". - * @name CKEDITOR.commandDefinition.prototype.context - * @type Boolean - * @default true + * Setting this property overrides {@link #contextSensitive} to ```true```. + * + * @property {Boolean} [context=true] */ /** * The editor modes within which the command can be executed. The execution * will have no action if the current mode is not listed in this property. - * @name CKEDITOR.commandDefinition.prototype.modes - * @type Object - * @default { wysiwyg:1 } + * + * editorInstance.addCommand( 'link', { + * exec: function( editor ) { + * // ... + * }, + * modes: { wysiwyg:1 } // Command is available in wysiwyg mode only. + * } ); + * + * @property {Object} [modes={ wysiwyg:1 }] * @see CKEDITOR.command#modes - * @example - * editorInstance.addCommand( 'link', - * { - * exec : function( editor ) - * { - * // ... - * }, - * modes : { wysiwyg:1 } // Command is available in wysiwyg mode only. - * }); */ diff --git a/core/config.js b/core/config.js index 4467e5f3aad..fbd5737f13e 100644 --- a/core/config.js +++ b/core/config.js @@ -4,15 +4,15 @@ */ /** - * @fileOverview Defines the {@link CKEDITOR.config} object that stores the + * @fileOverview Defines the {@link CKEDITOR.config} object that stores the * default configuration settings. */ /** - * Used in conjunction with {@link CKEDITOR.config#enterMode} - * and {@link CKEDITOR.config#shiftEnterMode} configuration - * settings to make the editor produce <p> tags when - * using the Enter key. + * Used in conjunction with ```{@link CKEDITOR.config#enterMode}``` + * and ```{@link CKEDITOR.config#shiftEnterMode}``` configuration + * settings to make the editor produce ```

``` tags when + * using the *Enter* key. * * @readonly * @property {Number} [=1] @@ -21,10 +21,10 @@ CKEDITOR.ENTER_P = 1; /** - * Used in conjunction with {@link CKEDITOR.config#enterMode} - * and {@link CKEDITOR.config#shiftEnterMode} configuration - * settings to make the editor produce <br> tags when - * using the Enter key. + * Used in conjunction with ```{@link CKEDITOR.config#enterMode}``` + * and ```{@link CKEDITOR.config#shiftEnterMode}``` configuration + * settings to make the editor produce ```
``` tags when + * using the *Enter* key. * * @readonly * @property {Number} [=2] @@ -33,10 +33,10 @@ CKEDITOR.ENTER_P = 1; CKEDITOR.ENTER_BR = 2; /** - * Used in conjunction with {@link CKEDITOR.config#enterMode} - * and {@link CKEDITOR.config#shiftEnterMode} configuration - * settings to make the editor produce <div> tags when - * using the Enter key. + * Used in conjunction with ```{@link CKEDITOR.config#enterMode}``` + * and ```{@link CKEDITOR.config#shiftEnterMode}``` configuration + * settings to make the editor produce ```

``` tags when + * using the *Enter* key. * * @readonly * @property {Number} [=3] @@ -110,10 +110,11 @@ CKEDITOR.config = { * UI direction or page element direction depending on the creators: * * Themed UI: The same with user interface language direction; * * Inline: The same with the editable element text direction; - * * 'ltr' - for Left-To-Right language (like English); - * * 'rtl' - for Right-To-Left languages (like Arabic). + * * ```'ltr'``` - for Left-To-Right language (like English); + * * ```'rtl'``` - for Right-To-Left languages (like Arabic). * * Example: + * * config.contentsLangDirection = 'rtl'; * * @cfg @@ -141,218 +142,184 @@ CKEDITOR.config = { enterMode: CKEDITOR.ENTER_P, /** - * Force the use of {@link CKEDITOR.config#enterMode} as line break regardless - * of the context. If, for example, {@link CKEDITOR.config#enterMode} is set - * to {@link CKEDITOR.ENTER_P}, pressing the Enter key inside a - * <div> element will create a new paragraph with <p> - * instead of a <div>. + * Force the use of ```{@link CKEDITOR.config#enterMode}``` as line break regardless + * of the context. If, for example, ```{@link CKEDITOR.config#enterMode}``` is set + * to ```{@link CKEDITOR#ENTER_P}```, pressing the *Enter* key inside a + * ```
``` element will create a new paragraph with ```

``` + * instead of a ```

```. + * + * // Not recommended. + * config.forceEnterMode = true; + * * @since 3.2.1 - * @type Boolean - * @default false - * @example - * // Not recommended. - * config.forceEnterMode = true; * @cfg - * @member CKEDITOR.editor */ forceEnterMode: false, /** - * Similarly to the {@link CKEDITOR.config#enterMode} setting, it defines the behavior - * of the Shift+Enter key combination. + * Similarly to the ```{@link CKEDITOR.config#enterMode}``` setting, it defines the behavior + * of the *Shift+Enter* key combination. + * * The allowed values are the following constants the behavior outlined below: - *
    - *
  • {@link CKEDITOR.ENTER_P} (1) – new <p> paragraphs are created;
    • - *
  • {@link CKEDITOR.ENTER_BR} (2) – lines are broken with <br> elements;
    • - *
  • {@link CKEDITOR.ENTER_DIV} (3) – new <div> blocks are created.
    • - *
- * @type Number - * @default {@link CKEDITOR.ENTER_BR} - * @example - * config.shiftEnterMode = CKEDITOR.ENTER_P; - * @cfg - * @member CKEDITOR.editor + * + * * ```{@link CKEDITOR.ENTER_P}``` (1) – new ```

``` paragraphs are created; + * * ```{@link CKEDITOR.ENTER_BR}``` (2) – lines are broken with ```
``` elements; + * * ```{@link CKEDITOR.ENTER_DIV}``` (3) – new ```

``` blocks are created. + * + * Example: + * + * config.shiftEnterMode = CKEDITOR.ENTER_P; + * + * @cfg {Number} [=CKEDITOR.ENTER_BR] */ shiftEnterMode: CKEDITOR.ENTER_BR, /** - * Sets the DOCTYPE to be used when loading the editor content as HTML. - * @type String - * @default '<!DOCTYPE html>' - * @example - * // Set the DOCTYPE to the HTML 4 (Quirks) mode. - * config.docType = '<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">'; + * Sets the ```DOCTYPE``` to be used when loading the editor content as HTML. + * + * // Set the DOCTYPE to the HTML 4 (Quirks) mode. + * config.docType = ''; + * * @cfg - * @member CKEDITOR.editor */ docType: '', /** - * Sets the id attribute to be used on the body element + * Sets the ```id``` attribute to be used on the ```body``` element * of the editing area. This can be useful when you intend to reuse the original CSS * file you are using on your live website and want to assign the editor the same ID * as the section that will include the contents. In this way ID-specific CSS rules will * be enabled. + * + * config.bodyId = 'contents_id'; + * * @since 3.1 - * @type String - * @default '' (empty) - * @example - * config.bodyId = 'contents_id'; * @cfg - * @member CKEDITOR.editor */ bodyId: '', /** - * Sets the class attribute to be used on the body element + * Sets the ```class``` attribute to be used on the ```body``` element * of the editing area. This can be useful when you intend to reuse the original CSS * file you are using on your live website and want to assign the editor the same class * as the section that will include the contents. In this way class-specific CSS rules will * be enabled. + * + * config.bodyClass = 'contents'; + * * @since 3.1 - * @type String - * @default '' (empty) - * @example - * config.bodyClass = 'contents'; * @cfg - * @member CKEDITOR.editor */ bodyClass: '', /** - * Indicates whether the contents to be edited are being input as a full - * HTML page. A full page includes the <html>, - * <head>, and <body> elements. + * Indicates whether the contents to be edited are being input as a full HTML page. + * A full page includes the ``````, ``````, and `````` elements. * The final output will also reflect this setting, including the - * <body> contents only if this setting is disabled. + * `````` contents only if this setting is disabled. + * + * config.fullPage = true; + * * @since 3.1 - * @type Boolean - * @default false - * @example - * config.fullPage = true; * @cfg - * @member CKEDITOR.editor */ fullPage: false, /** * The height of the editing area (that includes the editor content). This - * can be an integer, for pixel sizes, or any CSS-defined length unit.
- *
- * Note: Percent units (%) are not supported. - * @type Number|String - * @default 200 - * @example - * config.height = 500; // 500 pixels. - * @example - * config.height = '25em'; // CSS length. - * @example - * config.height = '300px'; // CSS length. - * @cfg - * @member CKEDITOR.editor + * can be an integer, for pixel sizes, or any CSS-defined length unit. + * + * **Note:** Percent units (%) are not supported. + * + * config.height = 500; // 500 pixels. + * config.height = '25em'; // CSS length. + * config.height = '300px'; // CSS length. + * + * @cfg {Number/String} */ height: 200, /** * Comma separated list of plugins to be used for an editor instance, * besides, the actual plugins that to be loaded could be still affected by two other settings: - * {@link CKEDITOR.config#extraPlugins} and {@link CKEDITOR.config#removePlugins}. - * @type String - * @example - * @cfg - * @member CKEDITOR.editor + * ```{@link CKEDITOR.config#extraPlugins}``` and ```{@link CKEDITOR.config#removePlugins}```. + * + * @cfg {String} [=""] */ plugins: '', // %REMOVE_LINE% /** * A list of additional plugins to be loaded. This setting makes it easier - * to add new plugins without having to touch {@link CKEDITOR.config#plugins} setting. - * @type String - * @example - * config.extraPlugins = 'myplugin,anotherplugin'; + * to add new plugins without having to touch ```{@link CKEDITOR.config#plugins}``` setting. + * + * config.extraPlugins = 'myplugin,anotherplugin'; + * * @cfg - * @member CKEDITOR.editor */ extraPlugins: '', /** * A list of plugins that must not be loaded. This setting makes it possible - * to avoid loading some plugins defined in the {@link CKEDITOR.config#plugins} + * to avoid loading some plugins defined in the ```{@link CKEDITOR.config#plugins}``` * setting, without having to touch it. - * @type String - * @example - * config.removePlugins = 'elementspath,save,font'; + * + * config.removePlugins = 'elementspath,save,font'; + * * @cfg - * @member CKEDITOR.editor */ removePlugins: '', /** * List of regular expressions to be executed on input HTML, - * indicating HTML source code that when matched, must not be available in the WYSIWYG + * indicating HTML source code that when matched, must **not** be available in the WYSIWYG * mode for editing. - * @type Array - * @default [] (empty array) - * @example - * config.protectedSource.push( /<\?[\s\S]*?\?>/g ); // PHP code - * config.protectedSource.push( /<%[\s\S]*?%>/g ); // ASP code - * config.protectedSource.push( /(]+>[\s|\S]*?<\/asp:[^\>]+>)|(]+\/>)/gi ); // ASP.Net code + * + * config.protectedSource.push( /<\?[\s\S]*?\?>/g ); // PHP code + * config.protectedSource.push( /<%[\s\S]*?%>/g ); // ASP code + * config.protectedSource.push( /(]+>[\s|\S]*?<\/asp:[^\>]+>)|(]+\/>)/gi ); // ASP.Net code + * * @cfg - * @member CKEDITOR.editor */ protectedSource: [], /** - * The editor tabindex value. - * @type Number - * @default 0 (zero) - * @example - * config.tabIndex = 1; + * The editor ```tabindex``` value. + * + * config.tabIndex = 1; + * * @cfg - * @member CKEDITOR.editor */ tabIndex: 0, /** * The editor UI outer width. This can be an integer, for pixel sizes, or - * any CSS-defined unit.
- *
- * Unlike the {@link CKEDITOR.config#height} setting, this + * any CSS-defined unit. + * + * Unlike the ```{@link CKEDITOR.config#height}``` setting, this * one will set the outer width of the entire editor UI, not for the * editing area only. - * @type String|Number - * @default '' (empty) - * @example - * config.width = 850; // 850 pixels wide. - * @example - * config.width = '75%'; // CSS unit. - * @cfg - * @member CKEDITOR.editor + * + * config.width = 850; // 850 pixels wide. + * config.width = '75%'; // CSS unit. + * + * @cfg {String/Number} */ width: '', /** * The base Z-index for floating dialog windows and popups. - * @type Number - * @default 10000 - * @example - * config.baseFloatZIndex = 2000 + * + * config.baseFloatZIndex = 2000; + * * @cfg - * @member CKEDITOR.editor */ baseFloatZIndex: 10000, /** * The keystrokes that are blocked by default as the browser implementation * is buggy. These default keystrokes are handled by the editor. - * @type Array - * @default [ - * CKEDITOR.CTRL + 66, // CTRL+B - * CKEDITOR.CTRL + 73, // CTRL+I - * CKEDITOR.CTRL + 85 // CTRL+U - * ] - * @cfg - * @member CKEDITOR.editor + * + * @cfg {Array} [=[ CKEDITOR.CTRL + 66, CKEDITOR.CTRL + 73, CKEDITOR.CTRL + 85 ] // CTRL+B,I,U] */ blockedKeystrokes: [ CKEDITOR.CTRL + 66, // CTRL+B @@ -364,30 +331,29 @@ CKEDITOR.config = { /** * Indicates that some of the editor features, like alignment and text * direction, should use the "computed value" of the feature to indicate its - * on/off state instead of using the "real value".
- *
+ * on/off state instead of using the "real value". + * * If enabled in a Left-To-Right written document, the "Left Justify" * alignment button will be shown as active, even if the alignment style is not * explicitly applied to the current paragraph in the editor. - * @name CKEDITOR.config.useComputedState - * @type Boolean - * @default true + * + * config.useComputedState = false; + * * @since 3.4 - * @example - * config.useComputedState = false; + * @cfg {Boolean} [useComputedState=true] */ /** * The base user interface color to be used by the editor. Not all skins are * compatible with this setting. - * @name CKEDITOR.config.uiColor - * @type String - * @example - * // Using a color code. - * config.uiColor = '#AADC6E'; - * @example - * // Using an HTML color name. - * config.uiColor = 'Gold'; + * + * // Using a color code. + * config.uiColor = '#AADC6E'; + * + * // Using an HTML color name. + * config.uiColor = 'Gold'; + * + * @cfg {String} uiColor */ // PACKAGER_RENAME( CKEDITOR.config ) diff --git a/core/editor.js b/core/editor.js index 9b7cb50849a..24ae45e7f0b 100644 --- a/core/editor.js +++ b/core/editor.js @@ -107,7 +107,7 @@ * the page when creating the editor. * * var editor = CKEDITOR.instances.editor1; - * alert( editor.config.skin ); // "kama" e.g. + * alert( editor.config.skin ); // 'kama' e.g. * * @property {CKEDITOR.config} */ @@ -129,10 +129,7 @@ */ this.focusManager = new CKEDITOR.focusManager( this ); - /** - * @property {CKEDITOR.htmlDataProcessor} - * @todo - */ + // Documented in dataprocessor.js. this.dataProcessor = new CKEDITOR.htmlDataProcessor( this ); /** @@ -307,7 +304,7 @@ * setting or taken from the ```tabindex``` attribute of the * ```{@link #element}``` associated with the editor. * - * alert( editor.tabIndex ); // E.g. "0" + * alert( editor.tabIndex ); // E.g. '0' * * @property {Number} [=0] */ @@ -336,7 +333,7 @@ * The code for the language resources that have been loaded * for the user interface elements of this editor instance. * - * alert( editor.langCode ); // E.g. "en" + * alert( editor.langCode ); // E.g. 'en' * * @property {String} */ @@ -407,7 +404,7 @@ * An object that contains references to all plugins used by this * editor instance. * - * alert( editor.plugins.dialog.path ); // E.g. "http://example.com/ckeditor/plugins/dialog/" + * alert( editor.plugins.dialog.path ); // E.g. 'http://example.com/ckeditor/plugins/dialog/' * * @property {Object} */ @@ -524,9 +521,9 @@ * Destroys the editor instance, releasing all resources used by it. * If the editor replaced an element, the element will be recovered. * - * alert( CKEDITOR.instances.editor1 ); // E.g "object" + * alert( CKEDITOR.instances.editor1 ); // E.g 'object' * CKEDITOR.instances.editor1.destroy(); - * alert( CKEDITOR.instances.editor1 ); // "undefined" + * alert( CKEDITOR.instances.editor1 ); // 'undefined' * * @param {Boolean} [noUpdate] If the instance is replacing a DOM * element, this parameter indicates whether or not to update the @@ -819,7 +816,7 @@ * else * window.attachEvent( 'onbeforeunload', beforeUnload ); * - * @returns {Boolean} ```"true"``` if the contents contain changes. + * @returns {Boolean} ```true``` if the contents contain changes. */ checkDirty: function() { return this._.previousValue !== this.getSnapshot(); @@ -830,9 +827,9 @@ * ```{@link #checkDirty}``` will return ```false``` if the user will not * have made further changes to the contents. * - * alert( editor.checkDirty() ); // E.g. "true" + * alert( editor.checkDirty() ); // E.g. 'true' * editor.resetDirty(); - * alert( editor.checkDirty() ); // "false" + * alert( editor.checkDirty() ); // 'false' */ resetDirty: function() { this._.previousValue = this.getSnapshot(); @@ -935,18 +932,10 @@ CKEDITOR.ELEMENT_MODE_INLINE = 3; * config.htmlEncodeOutput = true; * * @since 3.1 - * @property {Boolean} [htmlEncodeOutput=false] + * @cfg {Boolean} [htmlEncodeOutput=false] * @member CKEDITOR.config */ -/** - * The outer most element in the DOM tree in which the editable element resides, it's provided - * by the concrete editor creator after editor UI is created and is not subjected to - * be modified. - * - * @property {CKEDITOR.dom.element} container - */ - /** * If ```true```, makes the editor start in read-only state. Otherwise, it will check * if the linked ```