8
0
Просмотр исходного кода

Docs: Context and ContextPlugin API docs corrected. [skip ci]

Anna Tomanek 5 лет назад
Родитель
Сommit
82baaeec3e

+ 37 - 37
packages/ckeditor5-core/src/context.js

@@ -14,29 +14,29 @@ import Locale from '@ckeditor/ckeditor5-utils/src/locale';
 import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
 
 /**
- * Provides a common, higher level environment for solutions which use multiple {@link module:core/editor/editor~Editor editors}
- * or/and plugins that work outside of an editor. Use it instead of {@link module:core/editor/editor~Editor.create `Editor.create()`}
+ * Provides a common, higher-level environment for solutions that use multiple {@link module:core/editor/editor~Editor editors}
+ * or plugins that work outside the editor. Use it instead of {@link module:core/editor/editor~Editor.create `Editor.create()`}
  * in advanced application integrations.
  *
- * All configuration options passed to a `Context` will be used as default options for editor instances initialized in that context.
+ * All configuration options passed to a context will be used as default options for editor instances initialized in that context.
  *
- * {@link module:core/contextplugin~ContextPlugin `ContextPlugin`s} passed to a `Context` instance will be shared among all
- * editor instances initialized in that context. These will be the same plugin instances for all the editors.
+ * {@link module:core/contextplugin~ContextPlugin Context plugins} passed to a context instance will be shared among all
+ * editor instances initialized in this context. These will be the same plugin instances for all the editors.
  *
- * **Note:** `Context` can only be initialized with {@link module:core/contextplugin~ContextPlugin `ContextPlugin`s}
- * (e.g. [comments](https://ckeditor.com/collaboration/comments/)). Regular {@link module:core/plugin~Plugin `Plugin`s} require an
- * editor instance to work and cannot be added to a `Context`.
+ * **Note:** The context can only be initialized with {@link module:core/contextplugin~ContextPlugin context plugins}
+ * (e.g. [comments](https://ckeditor.com/collaboration/comments/)). Regular {@link module:core/plugin~Plugin plugins} require an
+ * editor instance to work and cannot be added to a context.
  *
- * **Note:** You can add `ContextPlugin` to an editor instance, though.
+ * **Note:** You can add a context plugin to an editor instance, though.
  *
- * If you are using multiple editor instances on one page and use any `ContextPlugin`s, create `Context` to share configuration and plugins
- * among those editors. Some plugins will use the information about all existing editors to better integrate between them.
+ * If you are using multiple editor instances on one page and use any context plugins, create a context to share the configuration and
+ * plugins among these editors. Some plugins will use the information about all existing editors to better integrate between them.
  *
- * If you are using plugins that do not require an editor to work (e.g. [comments](https://ckeditor.com/collaboration/comments/))
- * enable and configure them using `Context`.
+ * If you are using plugins that do not require an editor to work (e.g. [comments](https://ckeditor.com/collaboration/comments/)),
+ * enable and configure them using the context.
  *
- * If you are using only a single editor on each page use {@link module:core/editor/editor~Editor.create `Editor.create()`} instead.
- * In such case, `Context` instance will be created by the editor instance in a transparent way.
+ * If you are using only a single editor on each page, use {@link module:core/editor/editor~Editor.create `Editor.create()`} instead.
+ * In such case, a context instance will be created by the editor instance in a transparent way.
  *
  * See {@link module:core/context~Context.create `Context.create()`} for usage examples.
  */
@@ -44,13 +44,13 @@ export default class Context {
 	/**
 	 * Creates a context instance with a given configuration.
 	 *
-	 * Usually, not to be used directly. See the static {@link module:core/context~Context.create `create()`} method.
+	 * Usually not to be used directly. See the static {@link module:core/context~Context.create `create()`} method.
 	 *
-	 * @param {Object} [config={}] The context config.
+	 * @param {Object} [config={}] The context configuration.
 	 */
 	constructor( config ) {
 		/**
-		 * Holds all configurations specific to this context instance.
+		 * Stores all the configurations specific to this context instance.
 		 *
 		 * @readonly
 		 * @type {module:utils/config~Config}
@@ -85,7 +85,7 @@ export default class Context {
 		this.t = this.locale.t;
 
 		/**
-		 * List of editors to which this context instance is injected.
+		 * A list of editors that this context instance is injected to.
 		 *
 		 * @readonly
 		 * @type {module:utils/collection~Collection}
@@ -105,10 +105,10 @@ export default class Context {
 	}
 
 	/**
-	 * Loads and initializes plugins specified in the config.
+	 * Loads and initializes plugins specified in the configuration.
 	 *
 	 * @returns {Promise.<module:core/plugin~LoadedPlugins>} A promise which resolves
-	 * once the initialization is completed providing an array of loaded plugins.
+	 * once the initialization is completed, providing an array of loaded plugins.
 	 */
 	initPlugins() {
 		const plugins = this.config.get( 'plugins' ) || [];
@@ -135,7 +135,7 @@ export default class Context {
 				 * @error context-initplugins-invalid-plugin
 				 */
 				throw new CKEditorError(
-					'context-initplugins-invalid-plugin: Only a plugin marked as a ContextPlugin is allowed to be used with a context.',
+					'context-initplugins-invalid-plugin: Only a plugin marked as a context plugin is allowed to be used with a context.',
 					null,
 					{ Plugin }
 				);
@@ -146,8 +146,8 @@ export default class Context {
 	}
 
 	/**
-	 * Destroys the context instance, and all editors used with the context.
-	 * Releasing all resources used by the context.
+	 * Destroys the context instance and all editors used with the context,
+	 * releasing all resources used by the context.
 	 *
 	 * @returns {Promise} A promise that resolves once the context instance is fully destroyed.
 	 */
@@ -159,10 +159,10 @@ export default class Context {
 	/**
 	 * Adds a reference to the editor which is used with this context.
 	 *
-	 * When the given editor has created the context then the reference to this editor will be stored
+	 * When the given editor has created the context, the reference to this editor will be stored
 	 * as a {@link ~Context#_contextOwner}.
 	 *
-	 * This method should be used only by the editor.
+	 * This method should only be used by the editor.
 	 *
 	 * @protected
 	 * @param {module:core/editor/editor~Editor} editor
@@ -189,13 +189,13 @@ export default class Context {
 
 	/**
 	 * Removes a reference to the editor which was used with this context.
-	 * When the context was created by the given editor then the context will be destroyed.
+	 * When the context was created by the given editor, the context will be destroyed.
 	 *
-	 * This method should be used only by the editor.
+	 * This method should only be used by the editor.
 	 *
 	 * @protected
 	 * @param {module:core/editor/editor~Editor} editor
-	 * @return {Promise} A promise that resolves once the editor is removed from the context or when the context has been destroyed.
+	 * @return {Promise} A promise that resolves once the editor is removed from the context or when the context was destroyed.
 	 */
 	_removeEditor( editor ) {
 		if ( this.editors.has( editor ) ) {
@@ -210,12 +210,12 @@ export default class Context {
 	}
 
 	/**
-	 * Returns context configuration which will be copied to editors created using this context.
+	 * Returns the context configuration which will be copied to the editors created using this context.
 	 *
-	 * The configuration returned by this method has removed plugins configuration - plugins are shared with all editors
+	 * The configuration returned by this method has the plugins configuration removed &mdash; plugins are shared with all editors
 	 * through another mechanism.
 	 *
-	 * This method should be used only by the editor.
+	 * This method should only be used by the editor.
 	 *
 	 * @protected
 	 * @returns {Object} Configuration as a plain object.
@@ -236,14 +236,14 @@ export default class Context {
 	 * Creates and initializes a new context instance.
 	 *
 	 *		const commonConfig = { ... }; // Configuration for all the plugins and editors.
-	 *		const editorPlugins = [ ... ]; // Regular `Plugin`s here.
+	 *		const editorPlugins = [ ... ]; // Regular plugins here.
 	 *
 	 *		Context
 	 *			.create( {
-	 *				// Only `ContextPlugin`s here.
+	 *				// Only context plugins here.
 	 *				plugins: [ ... ],
 	 *
-	 *				// Configure language for all the editors (it cannot be overwritten).
+	 *				// Configure the language for all the editors (it cannot be overwritten).
 	 *				language: { ... },
 	 *
 	 *				// Configuration for context plugins.
@@ -271,14 +271,14 @@ export default class Context {
 	 *					{
 	 *						editorPlugins,
 	 *						context,
-	 *						toolbar: { ... } // You can overwrite context's configuration.
+	 *						toolbar: { ... } // You can overwrite the configuration of the context.
 	 *					}
 	 *				) );
 	 *
 	 *				return Promise.all( promises );
 	 *			} );
 	 *
-	 * @param {Object} [config] The context config.
+	 * @param {Object} [config] The context configuration.
 	 * @returns {Promise} A promise resolved once the context is ready. The promise resolves with the created context instance.
 	 */
 	static create( config ) {

+ 4 - 4
packages/ckeditor5-core/src/contextplugin.js

@@ -18,11 +18,11 @@ import mix from '@ckeditor/ckeditor5-utils/src/mix';
  * work within one editor instance or with one or more editor instances that use a single context.
  * It is the context plugin's role to implement handling for both modes.
  *
- * A couple of rules for interaction between editor plugins and context plugins:
+ * There are a few rules for interaction between the editor plugins and context plugins:
  *
- * * a context plugin can require another context plugin,
- * * an {@link module:core/plugin~Plugin editor plugin} can require a context plugin,
- * * a context plugin MUST NOT require an {@link module:core/plugin~Plugin editor plugin}.
+ * * A context plugin can require another context plugin.
+ * * An {@link module:core/plugin~Plugin editor plugin} can require a context plugin.
+ * * A context plugin MUST NOT require an {@link module:core/plugin~Plugin editor plugin}.
  *
  * @implements module:core/plugin~PluginInterface
  * @mixes module:utils/observablemixin~ObservableMixin

+ 2 - 2
packages/ckeditor5-core/src/editor/editor.js

@@ -121,8 +121,8 @@ export default class Editor {
 		 *
 		 * The editor is in one of the following states:
 		 *
-		 * * `initializing` &ndash; During the editor initialization (before {@link module:core/editor/editor~Editor.create `Editor.create()`})
-		 * finished its job.
+		 * * `initializing` &ndash; During the editor initialization (before
+		 * {@link module:core/editor/editor~Editor.create `Editor.create()`}) finished its job.
 		 * * `ready` &ndash; After the promise returned by the {@link module:core/editor/editor~Editor.create `Editor.create()`}
 		 * method is resolved.
 		 * * `destroyed` &ndash; Once the {@link #destroy `editor.destroy()`} method was called.

+ 6 - 6
packages/ckeditor5-core/src/plugin.js

@@ -221,7 +221,7 @@ mix( Plugin, ObservableMixin );
  *
  * The name should reflect the constructor name.
  *
- * To keep the plugin class definition tight it is recommended to define this property as a static getter:
+ * To keep the plugin class definition tight, it is recommended to define this property as a static getter:
  *
  *		export default class ImageCaption {
  *			static get pluginName() {
@@ -241,11 +241,11 @@ mix( Plugin, ObservableMixin );
  */
 
 /**
- * The second stage (after plugin {@link #constructor}) of plugin initialization.
+ * The second stage (after plugin {@link #constructor}) of the plugin initialization.
  * Unlike the plugin constructor this method can be asynchronous.
  *
  * A plugin's `init()` method is called after its {@link module:core/plugin~PluginInterface.requires dependencies} are initialized,
- * so in the same order as constructors of these plugins.
+ * so in the same order as the constructors of these plugins.
  *
  * **Note:** This method is optional. A plugin instance does not need to have it defined.
  *
@@ -254,7 +254,7 @@ mix( Plugin, ObservableMixin );
  */
 
 /**
- * The third (and last) stage of plugin initialization. See also {@link #constructor} and {@link #init}.
+ * The third (and last) stage of the plugin initialization. See also {@link #constructor} and {@link #init}.
  *
  * **Note:** This method is optional. A plugin instance does not need to have it defined.
  *
@@ -272,7 +272,7 @@ mix( Plugin, ObservableMixin );
  */
 
 /**
- * A flag which defines if plugin is allowed or not allowed to be use directly by a {@link module:core/context~Context}.
+ * A flag which defines if a plugin is allowed or not allowed to be used directly by a {@link module:core/context~Context}.
  *
  * @static
  * @readonly
@@ -280,7 +280,7 @@ mix( Plugin, ObservableMixin );
  */
 
 /**
- * Array of loaded plugins.
+ * An array of loaded plugins.
  *
  * @typedef {Array.<module:core/plugin~PluginInterface>} module:core/plugin~LoadedPlugins
  */

+ 13 - 13
packages/ckeditor5-core/src/plugincollection.js

@@ -21,16 +21,16 @@ import mix from '@ckeditor/ckeditor5-utils/src/mix';
  */
 export default class PluginCollection {
 	/**
-	 * Creates an instance of the PluginCollection class.
+	 * Creates an instance of the plugin collection class.
 	 * Allows loading and initializing plugins and their dependencies.
-	 * Allows to provide a list of already loaded plugins, these plugins won't be destroyed along with this collection.
+	 * Allows to provide a list of already loaded plugins. These plugins will not be destroyed along with this collection.
 	 *
 	 * @param {module:core/editor/editor~Editor|module:core/context~Context} context
 	 * @param {Array.<Function>} [availablePlugins] Plugins (constructors) which the collection will be able to use
 	 * when {@link module:core/plugincollection~PluginCollection#init} is used with plugin names (strings, instead of constructors).
 	 * Usually, the editor will pass its built-in plugins to the collection so they can later be
 	 * used in `config.plugins` or `config.removePlugins` by names.
-	 * @param {Iterable.<Array>} contextPlugins List of already initialized plugins represented by a
+	 * @param {Iterable.<Array>} contextPlugins A list of already initialized plugins represented by a
 	 * `[ PluginConstructor, pluginInstance ]` pair.
 	 */
 	constructor( context, availablePlugins = [], contextPlugins = [] ) {
@@ -47,7 +47,7 @@ export default class PluginCollection {
 		this._plugins = new Map();
 
 		/**
-		 * Map of plugin constructors which can be retrieved by their names.
+		 * A map of plugin constructors that can be retrieved by their names.
 		 *
 		 * @protected
 		 * @type {Map.<String|Function,Function>}
@@ -72,7 +72,7 @@ export default class PluginCollection {
 			this._contextPlugins.set( PluginConstructor, pluginInstance );
 			this._contextPlugins.set( pluginInstance, PluginConstructor );
 
-			// To make it possible to require plugin by its name.
+			// To make it possible to require a plugin by its name.
 			if ( PluginConstructor.pluginName ) {
 				this._availablePlugins.set( PluginConstructor.pluginName, PluginConstructor );
 			}
@@ -146,11 +146,11 @@ export default class PluginCollection {
 	}
 
 	/**
-	 * Checks if plugin is loaded.
+	 * Checks if a plugin is loaded.
 	 *
-	 *		// Check if 'Clipboard' plugin was loaded.
+	 *		// Check if the 'Clipboard' plugin was loaded.
 	 *		if ( editor.plugins.has( 'Clipboard' ) ) {
-	 *			// Now use clipboard plugin instance:
+	 *			// Now use the clipboard plugin instance:
 	 *			const clipboard = editor.plugins.get( 'Clipboard' );
 	 *
 	 *			// ...
@@ -237,7 +237,7 @@ export default class PluginCollection {
 					 * This is a generic error logged to the console when a JavaSript error is thrown during the initialization
 					 * of one of the plugins.
 					 *
-					 * If you correctly handled the promise returned by the editor's `create()` method (like shown below)
+					 * If you correctly handled the promise returned by the editor's `create()` method (like shown below),
 					 * you will find the original error logged to the console, too:
 					 *
 					 *		ClassicEditor.create( document.getElementById( 'editor' ) )
@@ -283,11 +283,11 @@ export default class PluginCollection {
 
 						if ( PluginConstructor.isContextPlugin && !RequiredPluginConstructor.isContextPlugin ) {
 							/**
-							 * If a plugin is a `ContextPlugin` all plugins it requires should also be a `ContextPlugin`,
-							 * instead of `Plugin`. In other words, if one plugin can be used in the `Context`,
-							 * all its requirements also should be ready to be used in the`Context`. Note that context
+							 * If a plugin is a context plugin, all plugins it requires should also be context plugins
+							 * instead of plugins. In other words, if one plugin can be used in the context,
+							 * all its requirements should also be ready to be used in the context. Note that the context
 							 * provides only a part of the API provided by the editor. If one plugin needs a full
-							 * editor API, all plugins which require it, are considered as plugins which need a full
+							 * editor API, all plugins which require it are considered as plugins that need a full
 							 * editor API.
 							 *
 							 * @error plugincollection-context-required