Procházet zdrojové kódy

Merge stable into master

CKEditor Bot před 5 roky
rodič
revize
9701cc8ff1

+ 1 - 1
docs/_snippets/examples/balloon-editor.html

@@ -2,7 +2,7 @@
 	<h2>Walking the capitals of Europe: Warsaw</h2>
 
 	<figure class="media">
-		<oembed url="https://www.youtube.com/watch?v=WmWFwGLA1kQ"></oembed>
+		<oembed url="https://www.youtube.com/watch?v=7YRyFvjA_a8"></oembed>
 	</figure>
 
 	<p>If you enjoyed my previous articles in which we discussed wandering around <a href="https://en.wikipedia.org/wiki/Copenhagen">Copenhagen</a> and <a href="https://en.wikipedia.org/wiki/Vilnius">Vilnius</a>, you’ll definitely love exploring <a href="https://en.wikipedia.org/wiki/Warsaw">Warsaw</a>.</p>

+ 1 - 1
docs/framework/guides/tutorials/implementing-a-block-widget.md

@@ -22,7 +22,7 @@ While it is not strictly necessary to read the {@link framework/guides/quick-sta
 The tutorial will also reference various parts of the {@link framework/guides/architecture/intro CKEditor 5 architecture} section as you go. While reading them is not necessary to finish this tutorial, it is recommended to read these guides at some point to get a better understanding of the mechanisms used in this tutorial.
 
 <info-box>
-	If you want to use own event handler for events triggered by your widget then you must wrap it by a container that has a `data-cke-ignore-events` attribute to exclude it from editor's default handlers. Refer to {@link framework/guides/deep-dive/widget-internals#exclude-dom-events-from-default-handlers Exclude DOM events from default handlers} for more details.
+	If you want to use your own event handler for events triggered by your widget, you must wrap it with a container that has a `data-cke-ignore-events` attribute to exclude it from the editor's default handlers. Refer to {@link framework/guides/deep-dive/widget-internals#exclude-dom-events-from-default-handlers Exclude DOM events from default handlers} for more details.
 </info-box>
 
 ## Let's start

+ 1 - 1
docs/framework/guides/tutorials/using-react-in-a-widget.md

@@ -26,7 +26,7 @@ There are a couple of things you should know before you start:
 * Various parts of the {@link framework/guides/architecture/intro CKEditor 5 architecture} section will be referenced as you go. While reading them is not necessary to finish this tutorial, it is recommended to read those guides at some point to get a better understanding of the mechanisms used in this tutorial.
 
 <info-box>
-	If you want to use own event handler for events triggered by your React component then you must wrap it by a container that has a `data-cke-ignore-events` attribute to exclude it from editor's default handlers. Refer to {@link framework/guides/deep-dive/widget-internals#exclude-dom-events-from-default-handlers Exclude DOM events from default handlers} for more details.
+	If you want to use your own event handler for events triggered by your React component, you must wrap it with a container that has a `data-cke-ignore-events` attribute to exclude it from the editor's default handlers. Refer to {@link framework/guides/deep-dive/widget-internals#exclude-dom-events-from-default-handlers Exclude DOM events from default handlers} for more details.
 </info-box>
 
 ## Let's start

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

@@ -21,11 +21,11 @@ export default class PluginCollection {
 	/**
 	 * 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 will not be destroyed along with this collection.
+	 * Allows providing 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).
+	 * when {@link module:core/plugincollection~PluginCollection#init} is used with the 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 A list of already initialized plugins represented by a
@@ -105,8 +105,8 @@ export default class PluginCollection {
 	 *			} );
 	 *		}
 	 *
-	 * **Note**: This method will throw error if plugin is not loaded. Use `{@link #has editor.plugins.has()}`
-	 * to check if plugin is available.
+	 * **Note**: This method will throw an error if a plugin is not loaded. Use `{@link #has editor.plugins.has()}`
+	 * to check if a plugin is available.
 	 *
 	 * @param {Function|String} key The plugin constructor or {@link module:core/plugin~PluginInterface.pluginName name}.
 	 * @returns {module:core/plugin~PluginInterface}
@@ -130,7 +130,7 @@ export default class PluginCollection {
 			 * property.
 			 *
 			 * **Note**: You can use `{@link module:core/plugincollection~PluginCollection#has editor.plugins.has()}`
-			 * to check if plugin was loaded.
+			 * to check if a plugin was loaded.
 			 *
 			 * @error plugincollection-plugin-not-loaded
 			 * @param {String} plugin The name of the plugin which is not loaded.
@@ -165,7 +165,7 @@ export default class PluginCollection {
 	 * @param {Array.<Function|String>} plugins An array of {@link module:core/plugin~PluginInterface plugin constructors}
 	 * or {@link module:core/plugin~PluginInterface.pluginName plugin names}. The second option (names) works only if
 	 * `availablePlugins` were passed to the {@link #constructor}.
-	 * @param {Array.<String|Function>} [removePlugins] Names of plugins or plugin constructors
+	 * @param {Array.<String|Function>} [removePlugins] Names of the plugins or plugin constructors
 	 * that should not be loaded (despite being specified in the `plugins` array).
 	 * @returns {Promise.<module:core/plugin~LoadedPlugins>} A promise which gets resolved once all plugins are loaded
 	 * and available in the collection.
@@ -196,7 +196,7 @@ export default class PluginCollection {
 			 * **If you see this warning when using one of the editor creators directly** (not a build), then it means
 			 * that you tried loading plugins by name. However, unlike CKEditor 4, CKEditor 5 does not implement a "plugin loader".
 			 * This means that CKEditor 5 does not know where to load the plugin modules from. Therefore, you need to
-			 * provide each plugin through reference (as a constructor function). Check out the examples in
+			 * provide each plugin through a reference (as a constructor function). Check out the examples in
 			 * {@glink builds/guides/integration/advanced-setup#scenario-2-building-from-source "Building from source"}.
 			 *
 			 * @error plugincollection-plugin-not-found
@@ -204,7 +204,7 @@ export default class PluginCollection {
 			 */
 			const errorId = 'plugincollection-plugin-not-found';
 
-			// Log the error, so it's more visible on the console. Hopefully, for better DX.
+			// Log the error, so it's more visible on the console. Hopefully, for a better DX.
 			logError( errorId, { plugins: missingPlugins } );
 
 			return Promise.reject( new CKEditorError( errorId, context, { plugins: missingPlugins } ) );
@@ -230,10 +230,10 @@ export default class PluginCollection {
 					/**
 					 * It was not possible to load the plugin.
 					 *
-					 * This is a generic error logged to the console when a JavaSript error is thrown during the initialization
+					 * This is a generic error logged to the console when a JavaScript 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 (as shown below),
 					 * you will find the original error logged to the console, too:
 					 *
 					 *		ClassicEditor.create( document.getElementById( 'editor' ) )
@@ -398,11 +398,11 @@ export default class PluginCollection {
 			 * The second option is that your `node_modules/` directory contains duplicated versions of the same
 			 * CKEditor 5 packages. Normally, on clean installations, npm deduplicates packages in `node_modules/`, so
 			 * it may be enough to call `rm -rf node_modules && npm i`. However, if you installed conflicting versions
-			 * of packages, their dependencies may need to be installed in more than one version which may lead to this
+			 * of some packages, their dependencies may need to be installed in more than one version which may lead to this
 			 * warning.
 			 *
 			 * Technically speaking, this error occurs because after adding a plugin to an existing editor build
-			 * dependencies of this plugin are being duplicated.
+			 * the dependencies of this plugin are being duplicated.
 			 * They are already built into that editor build and now get added for the second time as dependencies
 			 * of the plugin you are installing.
 			 *

+ 59 - 59
packages/ckeditor5-engine/src/conversion/downcastdispatcher.js

@@ -15,8 +15,8 @@ import EmitterMixin from '@ckeditor/ckeditor5-utils/src/emittermixin';
 import mix from '@ckeditor/ckeditor5-utils/src/mix';
 
 /**
- * Downcast dispatcher is a central point of downcasting (conversion from the model to the view), which is a process of reacting to changes
- * in the model and firing a set of events. Callbacks listening to these events are called converters. The
+ * The downcast dispatcher is a central point of downcasting (conversion from the model to the view), which is a process of reacting
+ * to changes in the model and firing a set of events. Callbacks listening to these events are called converters. The
  * converters' role is to convert the model changes to changes in view (for example, adding view nodes or
  * changing attributes on view elements).
  *
@@ -52,7 +52,7 @@ import mix from '@ckeditor/ckeditor5-utils/src/mix';
  * * {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:addMarker} &ndash; If a marker was added.
  * * {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:removeMarker} &ndash; If a marker was removed.
  *
- * Note that changing a marker is done through removing the marker from the old range and adding it on the new range,
+ * Note that changing a marker is done through removing the marker from the old range and adding it to the new range,
  * so both events are fired.
  *
  * Finally, downcast dispatcher also handles firing events for the {@link module:engine/model/selection model selection}
@@ -65,9 +65,9 @@ import mix from '@ckeditor/ckeditor5-utils/src/mix';
  * * {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:addMarker}
  * &ndash; Fired for every marker that contains a selection.
  *
- * Unlike model tree and markers, events for selection are not fired for changes but for selection state.
+ * Unlike the model tree and the markers, the events for selection are not fired for changes but for a selection state.
  *
- * When providing custom listeners for downcast dispatcher, remember to check whether a given change has not been
+ * When providing custom listeners for a downcast dispatcher, remember to check whether a given change has not been
  * {@link module:engine/conversion/modelconsumable~ModelConsumable#consume consumed} yet.
  *
  * When providing custom listeners for downcast dispatcher, keep in mind that any callback that has
@@ -125,7 +125,7 @@ export default class DowncastDispatcher {
 		this.conversionApi = Object.assign( { dispatcher: this }, conversionApi );
 
 		/**
-		 * Maps conversion event names that will trigger element reconversion for given element name.
+		 * Maps conversion event names that will trigger element reconversion for a given element name.
 		 *
 		 * @type {Map<String, String>}
 		 * @private
@@ -217,7 +217,7 @@ export default class DowncastDispatcher {
 	}
 
 	/**
-	 * Starts conversion of attribute change on given `range`.
+	 * Starts a conversion of an attribute change on a given `range`.
 	 *
 	 * For each node in the given `range`, {@link #event:attribute attribute event} is fired with the passed data.
 	 *
@@ -253,15 +253,15 @@ export default class DowncastDispatcher {
 	}
 
 	/**
-	 * Starts a reconversion of an element. It will:
+	 * Starts the reconversion of an element. It will:
 	 *
-	 * * Fire a {@link #event:insert `insert` event} for the element to reconvert.
+	 * * Fire an {@link #event:insert `insert` event} for the element to reconvert.
 	 * * Fire an {@link #event:attribute `attribute` event} for element attributes.
 	 *
 	 * This will not reconvert children of the element if they have existing (already converted) views. For newly inserted child elements
 	 * it will behave the same as {@link #convertInsert}.
 	 *
-	 * Element reconversion is defined by a `triggerBy` configuration for
+	 * Element reconversion is defined by the `triggerBy` configuration for the
 	 * {@link module:engine/conversion/downcasthelpers~DowncastHelpers#elementToElement `elementToElement()`} conversion helper.
 	 *
 	 * @fires insert
@@ -321,16 +321,16 @@ export default class DowncastDispatcher {
 	}
 
 	/**
-	 * Starts model selection conversion.
+	 * Starts the model selection conversion.
 	 *
-	 * Fires events for given {@link module:engine/model/selection~Selection selection} to start selection conversion.
+	 * Fires events for a given {@link module:engine/model/selection~Selection selection} to start the selection conversion.
 	 *
 	 * @fires selection
 	 * @fires addMarker
 	 * @fires attribute
-	 * @param {module:engine/model/selection~Selection} selection Selection to convert.
-	 * @param {module:engine/model/markercollection~MarkerCollection} markers Markers connected with converted model.
-	 * @param {module:engine/view/downcastwriter~DowncastWriter} writer View writer that should be used to modify view document.
+	 * @param {module:engine/model/selection~Selection} selection The selection to convert.
+	 * @param {module:engine/model/markercollection~MarkerCollection} markers Markers connected with the converted model.
+	 * @param {module:engine/view/downcastwriter~DowncastWriter} writer View writer that should be used to modify the view document.
 	 */
 	convertSelection( selection, markers, writer ) {
 		const markersAtSelection = Array.from( markers.getMarkersAtPosition( selection.getFirstPosition() ) );
@@ -381,13 +381,13 @@ export default class DowncastDispatcher {
 	}
 
 	/**
-	 * Converts added marker. Fires {@link #event:addMarker addMarker} event for each item
-	 * in marker's range. If range is collapsed single event is dispatched. See event description for more details.
+	 * Converts the added marker. Fires the {@link #event:addMarker `addMarker`} event for each item
+	 * in the marker's range. If the range is collapsed, a single event is dispatched. See the event description for more details.
 	 *
 	 * @fires addMarker
 	 * @param {String} markerName Marker name.
-	 * @param {module:engine/model/range~Range} markerRange Marker range.
-	 * @param {module:engine/view/downcastwriter~DowncastWriter} writer View writer that should be used to modify view document.
+	 * @param {module:engine/model/range~Range} markerRange The marker range.
+	 * @param {module:engine/view/downcastwriter~DowncastWriter} writer View writer that should be used to modify the view document.
 	 */
 	convertMarkerAdd( markerName, markerRange, writer ) {
 		// Do not convert if range is in graveyard or not in the document (e.g. in DocumentFragment).
@@ -437,12 +437,12 @@ export default class DowncastDispatcher {
 	}
 
 	/**
-	 * Fires conversion of marker removal. Fires {@link #event:removeMarker removeMarker} event with provided data.
+	 * Fires the conversion of the marker removal. Fires the {@link #event:removeMarker `removeMarker`} event with the provided data.
 	 *
 	 * @fires removeMarker
 	 * @param {String} markerName Marker name.
-	 * @param {module:engine/model/range~Range} markerRange Marker range.
-	 * @param {module:engine/view/downcastwriter~DowncastWriter} writer View writer that should be used to modify view document.
+	 * @param {module:engine/model/range~Range} markerRange The marker range.
+	 * @param {module:engine/view/downcastwriter~DowncastWriter} writer View writer that should be used to modify the view document.
 	 */
 	convertMarkerRemove( markerName, markerRange, writer ) {
 		// Do not convert if range is in graveyard or not in the document (e.g. in DocumentFragment).
@@ -458,31 +458,31 @@ export default class DowncastDispatcher {
 	}
 
 	/**
-	 * Maps model element "insert" reconversion for given event names. The event names must be fully specified:
+	 * Maps the model element "insert" reconversion for given event names. The event names must be fully specified:
 	 *
-	 * * For "attribute" change event it should include main element name, ie: `'attribute:attributeName:elementName'`.
-	 * * For child nodes change events, those should use child event name as well, ie:
+	 * * For "attribute" change event, it should include the main element name, i.e: `'attribute:attributeName:elementName'`.
+	 * * For child node change events, these should use the child event name as well, i.e:
 	 *     * For adding a node: `'insert:childElementName'`.
 	 *     * For removing a node: `'remove:childElementName'`.
 	 *
-	 * **Note**: This method should not be used directly. A reconversion is defined by `triggerBy` configuration of the `elementToElement()`
-	 * conversion helper.
+	 * **Note**: This method should not be used directly. The reconversion is defined by the `triggerBy()` configuration of the
+	 * `elementToElement()` conversion helper.
 	 *
 	 * @protected
-	 * @param {String} modelName Main model element name for which events will trigger reconversion.
-	 * @param {String} eventName Name of an event that would trigger conversion for given model element.
+	 * @param {String} modelName The name of the main model element for which the events will trigger the reconversion.
+	 * @param {String} eventName The name of an event that would trigger conversion for a given model element.
 	 */
 	_mapReconversionTriggerEvent( modelName, eventName ) {
 		this._reconversionEventsMapping.set( eventName, modelName );
 	}
 
 	/**
-	 * Creates {@link module:engine/conversion/modelconsumable~ModelConsumable} with values to consume from given range,
+	 * Creates {@link module:engine/conversion/modelconsumable~ModelConsumable} with values to consume from a given range,
 	 * assuming that the range has just been inserted to the model.
 	 *
 	 * @private
-	 * @param {module:engine/model/range~Range} range Inserted range.
-	 * @returns {module:engine/conversion/modelconsumable~ModelConsumable} Values to consume.
+	 * @param {module:engine/model/range~Range} range The inserted range.
+	 * @returns {module:engine/conversion/modelconsumable~ModelConsumable} The values to consume.
 	 */
 	_createInsertConsumable( range ) {
 		const consumable = new Consumable();
@@ -501,12 +501,12 @@ export default class DowncastDispatcher {
 	}
 
 	/**
-	 * Creates {@link module:engine/conversion/modelconsumable~ModelConsumable} with values to consume for given range.
+	 * Creates {@link module:engine/conversion/modelconsumable~ModelConsumable} with values to consume for a given range.
 	 *
 	 * @private
-	 * @param {module:engine/model/range~Range} range Affected range.
+	 * @param {module:engine/model/range~Range} range The affected range.
 	 * @param {String} type Consumable type.
-	 * @returns {module:engine/conversion/modelconsumable~ModelConsumable} Values to consume.
+	 * @returns {module:engine/conversion/modelconsumable~ModelConsumable} The values to consume.
 	 */
 	_createConsumableForRange( range, type ) {
 		const consumable = new Consumable();
@@ -522,9 +522,9 @@ export default class DowncastDispatcher {
 	 * Creates {@link module:engine/conversion/modelconsumable~ModelConsumable} with selection consumable values.
 	 *
 	 * @private
-	 * @param {module:engine/model/selection~Selection} selection Selection to create consumable from.
-	 * @param {Iterable.<module:engine/model/markercollection~Marker>} markers Markers which contains selection.
-	 * @returns {module:engine/conversion/modelconsumable~ModelConsumable} Values to consume.
+	 * @param {module:engine/model/selection~Selection} selection The selection to create the consumable from.
+	 * @param {Iterable.<module:engine/model/markercollection~Marker>} markers Markers that contain the selection.
+	 * @returns {module:engine/conversion/modelconsumable~ModelConsumable} The values to consume.
 	 */
 	_createSelectionConsumable( selection, markers ) {
 		const consumable = new Consumable();
@@ -561,7 +561,7 @@ export default class DowncastDispatcher {
 	}
 
 	/**
-	 * Clears conversion API object.
+	 * Clears the conversion API object.
 	 *
 	 * @private
 	 */
@@ -571,7 +571,7 @@ export default class DowncastDispatcher {
 	}
 
 	/**
-	 * Internal method for converting element insert. It will fire events for the inserted element and events for its attributes.
+	 * Internal method for converting element insertion. It will fire events for the inserted element and events for its attributes.
 	 *
 	 * @private
 	 * @fires insert
@@ -594,13 +594,13 @@ export default class DowncastDispatcher {
 	}
 
 	/**
-	 * Returns differ changes together with added "reconvert" type changes for {@link #reconvertElement}. Those are defined by
-	 * a `triggerBy` configuration for
+	 * Returns differ changes together with added "reconvert" type changes for {@link #reconvertElement}. These are defined by
+	 * a the `triggerBy()` configuration for the
 	 * {@link module:engine/conversion/downcasthelpers~DowncastHelpers#elementToElement `elementToElement()`} conversion helper.
 	 *
-	 * This method will remove every mapped insert or remove change with a single "reconvert" changes.
+	 * This method will remove every mapped insert or remove change with a single "reconvert" change.
 	 *
-	 * For instance: Having a `triggerBy` configuration defined for `<complex>` element that issues this element reconversion on
+	 * For instance: Having a `triggerBy()` configuration defined for the `<complex>` element that issues this element reconversion on
 	 * `foo` and `bar` attributes change, and a set of changes for this element:
 	 *
 	 *		const differChanges = [
@@ -616,7 +616,7 @@ export default class DowncastDispatcher {
 	 *			{ type: 'attribute', attributeKey: 'baz', ... }
 	 *		];
 	 *
-	 * In the example above the `'baz'` attribute change will fire an {@link #event:attribute attribute event}
+	 * In the example above, the `'baz'` attribute change will fire an {@link #event:attribute attribute event}
 	 *
 	 * @param {module:engine/model/differ~Differ} differ The differ object with buffered changes.
 	 * @returns {Array.<Object>} Updated set of changes.
@@ -676,14 +676,14 @@ export default class DowncastDispatcher {
 	}
 
 	/**
-	 * Checks if resulting change should trigger element reconversion.
+	 * Checks if the resulting change should trigger element reconversion.
 	 *
-	 * Those are defined by a `triggerBy` configuration for
+	 * These are defined by a `triggerBy()` configuration for the
 	 * {@link module:engine/conversion/downcasthelpers~DowncastHelpers#elementToElement `elementToElement()`} conversion helper.
 	 *
 	 * @private
-	 * @param {String} eventName Event name to check.
-	 * @param {String} elementName Element name to check.
+	 * @param {String} eventName The event name to check.
+	 * @param {String} elementName The element name to check.
 	 * @returns {Boolean}
 	 */
 	_isReconvertTriggerEvent( eventName, elementName ) {
@@ -760,7 +760,7 @@ export default class DowncastDispatcher {
 	 */
 
 	/**
-	 * Fired when a new marker is added to the model. Also fired when collapsed model selection that is inside a marker is converted.
+	 * Fired when a new marker is added to the model. Also fired when a collapsed model selection that is inside a marker is converted.
 	 *
 	 * `addMarker` is a namespace for a class of events. Names of actually called events follow this pattern:
 	 * `addMarker:markerName`. By specifying certain marker names, you can make the events even more gradual. For example,
@@ -770,17 +770,17 @@ export default class DowncastDispatcher {
 	 * If the marker range is not collapsed:
 	 *
 	 * * the event is fired for each item in the marker range one by one,
-	 * * `conversionApi.consumable` includes each item of the marker range and the consumable value is same as event name.
+	 * * `conversionApi.consumable` includes each item of the marker range and the consumable value is same as the event name.
 	 *
 	 * If the marker range is collapsed:
 	 *
 	 * * there is only one event,
-	 * * `conversionApi.consumable` includes marker range with event name.
+	 * * `conversionApi.consumable` includes marker range with the event name.
 	 *
-	 * If selection inside a marker is converted:
+	 * If the selection inside a marker is converted:
 	 *
 	 * * there is only one event,
-	 * * `conversionApi.consumable` includes selection instance with event name.
+	 * * `conversionApi.consumable` includes the selection instance with the event name.
 	 *
 	 * @event addMarker
 	 * @param {Object} data Additional information about the change.
@@ -795,7 +795,7 @@ export default class DowncastDispatcher {
 	 */
 
 	/**
-	 * Fired when marker is removed from the model.
+	 * Fired when a marker is removed from the model.
 	 *
 	 * `removeMarker` is a namespace for a class of events. Names of actually called events follow this pattern:
 	 * `removeMarker:markerName`. By specifying certain marker names, you can make the events even more gradual. For example,
@@ -879,8 +879,8 @@ function elementOrTextProxyToView( item, mapper ) {
  */
 
 /**
- * Stores information about what parts of processed model item are still waiting to be handled. After a piece of model item
- * was converted, appropriate consumable value should be {@link module:engine/conversion/modelconsumable~ModelConsumable#consume consumed}.
+ * Stores the information about what parts of a processed model item are still waiting to be handled. After a piece of a model item was
+ * converted, an appropriate consumable value should be {@link module:engine/conversion/modelconsumable~ModelConsumable#consume consumed}.
  *
  * @member {module:engine/conversion/modelconsumable~ModelConsumable} #consumable
  */
@@ -898,13 +898,13 @@ function elementOrTextProxyToView( item, mapper ) {
  */
 
 /**
- * The {@link module:engine/view/downcastwriter~DowncastWriter} instance used to manipulate data during conversion.
+ * The {@link module:engine/view/downcastwriter~DowncastWriter} instance used to manipulate the data during conversion.
  *
  * @member {module:engine/view/downcastwriter~DowncastWriter} #writer
  */
 
 /**
- * An object with an additional configuration which can be used during conversion process. Available only for data downcast conversion.
+ * An object with an additional configuration which can be used during the conversion process. Available only for data downcast conversion.
  *
  * @member {Object} #options
  */

+ 8 - 6
packages/ckeditor5-engine/src/conversion/downcasthelpers.js

@@ -59,9 +59,9 @@ export default class DowncastHelpers extends ConversionHelpers {
 	 *			}
 	 *		} );
 	 *
-	 * The element-to-element conversion supports a reconversion mechanism. This is helpful in conversion to complex view structures where
-	 * multiple atomic element-to-element and attribute-to-attribute or attribute-to-element could be used. By specifying `triggerBy`
-	 * events you can trigger reconverting model to a full view tree structures at once.
+	 * The element-to-element conversion supports the reconversion mechanism. This is helpful in the conversion to complex view structures
+	 * where multiple atomic element-to-element and attribute-to-attribute or attribute-to-element could be used. By specifying
+	 * `triggerBy()` events you can trigger reconverting the model to full view tree structures at once.
 	 *
 	 *		editor.conversion.for( 'downcast' ).elementToElement( {
 	 *			model: 'complex',
@@ -84,9 +84,11 @@ export default class DowncastHelpers extends ConversionHelpers {
 	 * @param {module:engine/view/elementdefinition~ElementDefinition|Function} config.view A view element definition or a function
 	 * that takes the model element and {@link module:engine/conversion/downcastdispatcher~DowncastConversionApi downcast conversion API}
 	 * as parameters and returns a view container element.
-	 * @param {Object} [config.triggerBy] Re-conversion triggers. At least one trigger must be defined.
-	 * @param {Array.<String>} config.triggerBy.attributes Name of element's attributes which change will trigger element reconversion.
-	 * @param {Array.<String>} config.triggerBy.children Name of direct children that adding or removing will trigger element reconversion.
+	 * @param {Object} [config.triggerBy] Reconversion triggers. At least one trigger must be defined.
+	 * @param {Array.<String>} config.triggerBy.attributes The name of the element's attributes whose change will trigger element
+	 * reconversion.
+	 * @param {Array.<String>} config.triggerBy.children The name of direct children whose adding or removing will trigger element
+	 * reconversion.
 	 * @returns {module:engine/conversion/downcasthelpers~DowncastHelpers}
 	 */
 	elementToElement( config ) {

+ 2 - 2
packages/ckeditor5-engine/src/view/observer/domeventobserver.js

@@ -36,8 +36,8 @@ import DomEventData from './domeventdata';
  */
 export default class DomEventObserver extends Observer {
 	/**
-	 * Type of the DOM event the observer should listen on. Array of types can be defined
-	 * if the obsever should listen to multiple DOM events.
+	 * Type of the DOM event the observer should listen to. Array of types can be defined
+	 * if the observer should listen to multiple DOM events.
 	 *
 	 * @readonly
 	 * @member {String|Array.<String>} #domEventType

+ 7 - 7
packages/ckeditor5-engine/src/view/observer/observer.js

@@ -14,7 +14,7 @@ import mix from '@ckeditor/ckeditor5-utils/src/mix';
  * Abstract base observer class. Observers are classes which listen to DOM events, do the preliminary
  * processing and fire events on the {@link module:engine/view/document~Document} objects.
  * Observers can also add features to the view, for instance by updating its status or marking elements
- * which need refresh on DOM events.
+ * which need a refresh on DOM events.
  *
  * @abstract
  */
@@ -26,7 +26,7 @@ export default class Observer {
 	 */
 	constructor( view ) {
 		/**
-		 * Instance of the view controller.
+		 * An instance of the view controller.
 		 *
 		 * @readonly
 		 * @member {module:engine/view/view~View}
@@ -34,7 +34,7 @@ export default class Observer {
 		this.view = view;
 
 		/**
-		 * Reference to the {@link module:engine/view/document~Document} object.
+		 * A reference to the {@link module:engine/view/document~Document} object.
 		 *
 		 * @readonly
 		 * @member {module:engine/view/document~Document}
@@ -42,7 +42,7 @@ export default class Observer {
 		this.document = view.document;
 
 		/**
-		 * State of the observer. If it is disabled events will not be fired.
+		 * State of the observer. If it is disabled no events will be fired.
 		 *
 		 * @readonly
 		 * @member {Boolean}
@@ -83,15 +83,15 @@ export default class Observer {
 	}
 
 	/**
-	 * Checks whether the given DOM event should be ignored (should not be turned into a synthetic view document event).
+	 * Checks whether a given DOM event should be ignored (should not be turned into a synthetic view document event).
 	 *
 	 * Currently, an event will be ignored only if its target or any of its ancestors has the `data-cke-ignore-events` attribute.
-	 * This attribute can be used inside structures generated by
+	 * This attribute can be used inside the structures generated by
 	 * {@link module:engine/view/downcastwriter~DowncastWriter#createUIElement `DowncastWriter#createUIElement()`} to ignore events
 	 * fired within a UI that should be excluded from CKEditor 5's realms.
 	 *
 	 * @param {Node} domTarget The DOM event target to check (usually an element, sometimes a text node and
-	 * potentially sometimes a document too).
+	 * potentially sometimes a document, too).
 	 * @returns {Boolean} Whether this event should be ignored by the observer.
 	 */
 	checkShouldIgnoreEventFromTarget( domTarget ) {

+ 13 - 13
packages/ckeditor5-engine/src/view/observer/selectionobserver.js

@@ -14,11 +14,11 @@ import MutationObserver from './mutationobserver';
 import { debounce } from 'lodash-es';
 
 /**
- * Selection observer class observes selection changes in the document. If selection changes on the document this
- * observer checks if there are any mutations and if DOM selection is different than the
- * {@link module:engine/view/document~Document#selection view selection}. Selection observer fires
- * {@link module:engine/view/document~Document#event:selectionChange} event only if selection change was the only change in the document
- * and DOM selection is different then the view selection.
+ * Selection observer class observes selection changes in the document. If a selection changes on the document this
+ * observer checks if there are any mutations and if the DOM selection is different from the
+ * {@link module:engine/view/document~Document#selection view selection}. The selection observer fires
+ * {@link module:engine/view/document~Document#event:selectionChange} event only if a selection change was the only change in the document
+ * and the DOM selection is different then the view selection.
  *
  * Note that this observer is attached by the {@link module:engine/view/view~View} and is available by default.
  *
@@ -61,7 +61,7 @@ export default class SelectionObserver extends Observer {
 		this.domConverter = view.domConverter;
 
 		/**
-		 * Set of documents which have added "selectionchange" listener to avoid adding listener twice to the same
+		 * A set of documents which have added `selectionchange` listener to avoid adding a listener twice to the same
 		 * document.
 		 *
 		 * @private
@@ -119,8 +119,8 @@ export default class SelectionObserver extends Observer {
 
 	/**
 	 * Selection change listener. {@link module:engine/view/observer/mutationobserver~MutationObserver#flush Flush} mutations, check if
-	 * selection changes and fires {@link module:engine/view/document~Document#event:selectionChange} event on every change
-	 * and {@link module:engine/view/document~Document#event:selectionChangeDone} when selection stop changing.
+	 * a selection changes and fires {@link module:engine/view/document~Document#event:selectionChange} event on every change
+	 * and {@link module:engine/view/document~Document#event:selectionChangeDone} when a selection stop changing.
 	 *
 	 * @private
 	 * @param {Event} domEvent DOM event.
@@ -140,8 +140,8 @@ export default class SelectionObserver extends Observer {
 		// Ensure the mutation event will be before selection event on all browsers.
 		this.mutationObserver.flush();
 
-		// If there were mutations then the view will be re-rendered by the mutation observer and selection
-		// will be updated, so selections will equal and event will not be fired, as expected.
+		// If there were mutations then the view will be re-rendered by the mutation observer and the selection
+		// will be updated, so the selections will equal and the event will not be fired, as expected.
 		const newViewSelection = this.domConverter.domSelectionToView( domSelection );
 
 		// Do not convert selection change if the new view selection has no ranges in it.
@@ -188,7 +188,7 @@ export default class SelectionObserver extends Observer {
 			// Prepare data for new selection and fire appropriate events.
 			this.document.fire( 'selectionChange', data );
 
-			// Call` #_fireSelectionChangeDoneDebounced` every time when `selectionChange` event is fired.
+			// Call `#_fireSelectionChangeDoneDebounced` every time when `selectionChange` event is fired.
 			// This function is debounced what means that `selectionChangeDone` event will be fired only when
 			// defined int the function time will elapse since the last time the function was called.
 			// So `selectionChangeDone` will be fired when selection will stop changing.
@@ -207,8 +207,8 @@ export default class SelectionObserver extends Observer {
 }
 
 /**
- * Fired when selection has changed. This event is fired only when the selection change was the only change that happened
- * in the document, and old selection is different then the new selection.
+ * Fired when a selection has changed. This event is fired only when the selection change was the only change that happened
+ * in the document, and the old selection is different then the new selection.
  *
  * Introduced by {@link module:engine/view/observer/selectionobserver~SelectionObserver}.
  *

+ 1 - 1
packages/ckeditor5-html-embed/README.md

@@ -5,7 +5,7 @@ CKEditor 5 HTML embed feature
 [![Dependency Status](https://david-dm.org/ckeditor/ckeditor5-html-embed/status.svg)](https://david-dm.org/ckeditor/ckeditor5-html-embed)
 [![devDependency Status](https://david-dm.org/ckeditor/ckeditor5-html-embed/dev-status.svg)](https://david-dm.org/ckeditor/ckeditor5-html-embed?type=dev)
 
-This package implements the HTML embed feature for CKEditor 5.
+This package implements the HTML embed feature for CKEditor 5. It allows embedding an arbitrary HTML snippet in the rich-text editor.
 
 ## Demo
 

+ 3 - 3
packages/ckeditor5-link/src/autolink.js

@@ -14,7 +14,7 @@ import { addLinkProtocolIfApplicable } from './utils';
 
 const MIN_LINK_LENGTH_WITH_SPACE_AT_END = 4; // Ie: "t.co " (length 5).
 
-// This was tweak from https://gist.github.com/dperini/729294.
+// This was a tweak from https://gist.github.com/dperini/729294.
 const URL_REG_EXP = new RegExp(
 	// Group 1: Line start or after a space.
 	'(^|\\s)' +
@@ -95,12 +95,12 @@ export default class AutoLink extends Plugin {
 		const editor = this.editor;
 
 		const watcher = new TextWatcher( editor.model, text => {
-			// 1. Detect "Space" after a text with a potential link.
+			// 1. Detect <kbd>Space</kbd> after a text with a potential link.
 			if ( !isSingleSpaceAtTheEnd( text ) ) {
 				return;
 			}
 
-			// 2. Check text before last typed "Space".
+			// 2. Check text before last typed <kbd>Space</kbd>.
 			const url = getUrlAtTextEnd( text.substr( 0, text.length - 1 ) );
 
 			if ( url ) {

+ 5 - 5
packages/ckeditor5-link/src/utils.js

@@ -35,7 +35,7 @@ export function isLinkElement( node ) {
 }
 
 /**
- * Creates link {@link module:engine/view/attributeelement~AttributeElement} with the provided `href` attribute.
+ * Creates a link {@link module:engine/view/attributeelement~AttributeElement} with the provided `href` attribute.
  *
  * @param {String} href
  * @param {module:engine/conversion/downcastdispatcher~DowncastConversionApi} conversionApi
@@ -154,11 +154,11 @@ export function isEmail( value ) {
 }
 
 /**
- * Adds protocol prefix to the specified `link` when:
+ * Adds the protocol prefix to the specified `link` when:
  *
- * * it doesn't contain it already, and there is a {@link module:link/link~LinkConfig#defaultProtocol `defaultProtocol` }
- * config value provided
- * * or the link is an email address
+ * * it does not contain it already, and there is a {@link module:link/link~LinkConfig#defaultProtocol `defaultProtocol` }
+ * configuration value provided,
+ * * or the link is an email address.
  *
  *
  * @params {String} link

+ 7 - 7
packages/ckeditor5-list/src/liststyleediting.js

@@ -114,9 +114,9 @@ export default class ListStyleEditing extends Plugin {
 		const editor = this.editor;
 		const model = editor.model;
 
-		// First the most-outer `listItem` in the first list reference.
-		// If found, lists should be merged and this `listItem` provides the `listStyle` attribute
-		// and it' also a starting point when searching for items in the second list.
+		// First the outer-most`listItem` in the first list reference.
+		// If found, the lists should be merged and this `listItem` provides the `listStyle` attribute
+		// and it is also a starting point when searching for items in the second list.
 		let firstMostOuterItem;
 
 		// Check whether the removed content is between two lists.
@@ -249,8 +249,8 @@ function downcastListStyleAttribute() {
 
 	// Checks whether specified list items belong to the same list.
 	//
-	// @param {module:engine/model/element~Element} listItem1 The first list item to check.
-	// @param {module:engine/model/element~Element|null} listItem2 The second list item to check.
+	// @param {module:engine/model/element~Element} `listItem1` The first list item to check.
+	// @param {module:engine/model/element~Element|null} `listItem2` The second list item to check.
 	// @returns {Boolean}
 	function areRepresentingSameList( listItem1, listItem2 ) {
 		return listItem2 &&
@@ -295,7 +295,7 @@ function fixListAfterIndentListCommand( editor ) {
 
 		const itemsToUpdate = changedItems.filter( item => item.getAttribute( 'listIndent' ) === rootIndent );
 
-		// A case where a few list items are intended must be checked separately
+		// A case where a few list items are indented must be checked separately
 		// since `getSiblingListItem()` returns the first changed element.
 		// ■ List item 1.
 		//     ○ [List item 2.
@@ -627,7 +627,7 @@ function restoreDefaultListStyle( editor ) {
 	};
 }
 
-// Returns `listItem` that were inserted or changed.
+// Returns the `listItem` that was inserted or changed.
 //
 // @param {Array.<Object>} changes The changes list returned by the differ.
 // @returns {Array.<module:engine/model/element~Element>}

+ 7 - 7
packages/ckeditor5-media-embed/src/ui/mediaformview.js

@@ -44,7 +44,7 @@ export default class MediaFormView extends View {
 		const t = locale.t;
 
 		/**
-		 * Tracks information about DOM focus in the form.
+		 * Tracks information about the DOM focus in the form.
 		 *
 		 * @readonly
 		 * @member {module:utils/focustracker~FocusTracker}
@@ -111,10 +111,10 @@ export default class MediaFormView extends View {
 			focusTracker: this.focusTracker,
 			keystrokeHandler: this.keystrokes,
 			actions: {
-				// Navigate form fields backwards using the Shift + Tab keystroke.
+				// Navigate form fields backwards using the <kbd>Shift</kbd> + <kbd>Tab</kbd> keystroke.
 				focusPrevious: 'shift + tab',
 
-				// Navigate form fields forwards using the Tab key.
+				// Navigate form fields forwards using the <kbd>Tab</kbd> key.
 				focusNext: 'tab'
 			}
 		} );
@@ -203,9 +203,9 @@ export default class MediaFormView extends View {
 		this.keystrokes.set( 'arrowup', stopPropagation );
 		this.keystrokes.set( 'arrowdown', stopPropagation );
 
-		// Intercept the "selectstart" event, which is blocked by default because of the default behavior
+		// Intercept the `selectstart` event, which is blocked by default because of the default behavior
 		// of the DropdownView#panelView.
-		// TODO: blocking "selectstart" in the #panelView should be configurable per–drop–down instance.
+		// TODO: blocking `selectstart` in the #panelView should be configurable per–drop–down instance.
 		this.listenTo( this.urlInputView.element, 'selectstart', ( evt, domEvt ) => {
 			domEvt.stopPropagation();
 		}, { priority: 'high' } );
@@ -287,7 +287,7 @@ export default class MediaFormView extends View {
 		labeledInput.infoText = this._urlInputViewInfoDefault;
 
 		inputField.on( 'input', () => {
-			// Display the tip text only when there's some value. Otherwise fall back to the default info text.
+			// Display the tip text only when there is some value. Otherwise fall back to the default info text.
 			labeledInput.infoText = inputField.element.value ? this._urlInputViewInfoTip : this._urlInputViewInfoDefault;
 			this.mediaURLInputValue = inputField.element.value.trim();
 		} );
@@ -336,7 +336,7 @@ export default class MediaFormView extends View {
  */
 
 /**
- * Fired when the form view is canceled, e.g. click on {@link #cancelButtonView}.
+ * Fired when the form view is canceled, e.g. by a click on {@link #cancelButtonView}.
  *
  * @event cancel
  */

+ 12 - 11
packages/ckeditor5-table/src/converters/upcasttable.js

@@ -10,7 +10,7 @@
 import { createEmptyTableCell } from '../utils/common';
 
 /**
- * View table element to model table element conversion helper.
+ * View the table element to model the table element conversion helper.
  *
  * This conversion helper converts the table element as well as table rows.
  *
@@ -64,13 +64,14 @@ export default function upcastTable() {
 }
 
 /**
- * Conversion helper that skips empty <tr> from upcasting at the beginning of the table.
+ * A conversion helper that skips empty <tr> from upcasting at the beginning of the table.
  *
- * Empty row is considered a table model error but when handling clipboard data there could be rows that contain only row-spanned cells
+ * AN empty row is considered a table model error but when handling clipboard data there could be rows that contain only row-spanned cells
  * and empty TR-s are used to maintain table structure (also {@link module:table/tablewalker~TableWalker} assumes that there are only rows
- * that have related tableRow elements).
+ * that have related `tableRow` elements).
  *
- * *Note:* Only first empty rows are removed because those have no meaning and solves issue of improper table with all empty rows.
+ * *Note:* Only the first empty rows are removed because those have no meaning and it solves the issue
+ * of an improper table with all empty rows.
  *
  * @returns {Function} Conversion helper.
  */
@@ -109,24 +110,24 @@ function scanTable( viewTable ) {
 	//			<tbody><tr><td>3</td></tr></tbody>
 	//		</table>
 	//
-	// But browsers will render rows in order as: 1 as heading and 2 and 3 as the body.
+	// But browsers will render rows in order as: 1 as the heading and 2 and 3 as the body.
 	const headRows = [];
 	const bodyRows = [];
 
 	// Currently the editor does not support more then one <thead> section.
-	// Only the first <thead> from the view will be used as heading rows and others will be converted to body rows.
+	// Only the first <thead> from the view will be used as a heading row and the others will be converted to body rows.
 	let firstTheadElement;
 
 	for ( const tableChild of Array.from( viewTable.getChildren() ) ) {
-		// Only <thead>, <tbody> & <tfoot> from allowed table children can have <tr>s.
-		// The else is for future purposes (mainly <caption>).
+		// Only `<thead>`, `<tbody>` & `<tfoot>` from allowed table children can have `<tr>`s.
+		// The else is for future purposes (mainly `<caption>`).
 		if ( tableChild.name === 'tbody' || tableChild.name === 'thead' || tableChild.name === 'tfoot' ) {
-			// Save the first <thead> in the table as table header - all other ones will be converted to table body rows.
+			// Save the first `<thead>` in the table as table header - all other ones will be converted to table body rows.
 			if ( tableChild.name === 'thead' && !firstTheadElement ) {
 				firstTheadElement = tableChild;
 			}
 
-			// There might be some extra empty text nodes between the `tr`s.
+			// There might be some extra empty text nodes between the `<tr>`s.
 			// Make sure further code operates on `tr`s only. (#145)
 			const trs = Array.from( tableChild.getChildren() ).filter( el => el.is( 'element', 'tr' ) );
 

+ 4 - 4
packages/ckeditor5-table/src/tableediting.js

@@ -81,10 +81,10 @@ export default class TableEditing extends Plugin {
 			isSelectable: true
 		} );
 
-		// Allow all $block content inside table cell.
+		// Allow all $block content inside a table cell.
 		schema.extend( '$block', { allowIn: 'tableCell' } );
 
-		// Disallow table in table.
+		// Disallow a table in a table.
 		schema.addChildCheck( ( context, childDefinition ) => {
 			if ( childDefinition.name == 'table' && Array.from( context.getNames() ).includes( 'table' ) ) {
 				return false;
@@ -110,7 +110,7 @@ export default class TableEditing extends Plugin {
 
 		conversion.for( 'editingDowncast' ).add( downcastInsertCell() );
 
-		// Duplicates code - needed to properly refresh paragraph inside table cell.
+		// Duplicates code - needed to properly refresh paragraph inside a table cell.
 		editor.conversion.for( 'editingDowncast' ).elementToElement( {
 			model: 'paragraph',
 			view: convertParagraphInTableCell,
@@ -121,7 +121,7 @@ export default class TableEditing extends Plugin {
 		conversion.attributeToAttribute( { model: 'colspan', view: 'colspan' } );
 		conversion.attributeToAttribute( { model: 'rowspan', view: 'rowspan' } );
 
-		// Table heading columns conversion (change of heading rows requires reconversion of the whole table).
+		// Table heading columns conversion (a change of heading rows requires a reconversion of the whole table).
 		conversion.for( 'editingDowncast' ).add( downcastTableHeadingColumnsChange() );
 
 		// Define all the commands.

+ 4 - 4
packages/ckeditor5-utils/src/ckeditorerror.js

@@ -140,7 +140,7 @@ export default class CKEditorError extends Error {
  * See also {@link module:utils/ckeditorerror~CKEditorError} for an explanation when to throw an error and when to log
  * a warning or an error to the console.
  *
- * @param {String} errorName Error name to be logged.
+ * @param {String} errorName The error name to be logged.
  * @param {Object} [data] Additional data to be logged.
  * @returns {String}
  */
@@ -149,8 +149,8 @@ export function logWarning( errorName, data ) {
 }
 
 /**
- * Logs an error to the console with properly formatted message and adds a link to the documentation.
- * Use whenever you want to log a error to the console.
+ * Logs an error to the console with a properly formatted message and adds a link to the documentation.
+ * Use whenever you want to log an error to the console.
  *
  *		/**
  *		 * There was a problem processing the configuration of the toolbar. The item with the given
@@ -165,7 +165,7 @@ export function logWarning( errorName, data ) {
  *
  * See also {@link module:utils/ckeditorerror~CKEditorError} for an explanation when to use each method.
  *
- * @param {String} errorName Error name to be logged.
+ * @param {String} errorName The error name to be logged.
  * @param {Object} [data] Additional data to be logged.
  * @returns {String}
  */