瀏覽代碼

Merge branch 'stable'

Piotrek Koszuliński 6 年之前
父節點
當前提交
630c55d225

+ 19 - 15
packages/ckeditor5-link/docs/features/link.md

@@ -5,7 +5,7 @@ category: features
 
 {@snippet features/build-link-source}
 
-The {@link module:link/link~Link} feature brings support for link editing to the editor. It allows for inserting hyperlinks into the edited content and offers the UI to create and edit them.
+The {@link module:link/link~Link} feature brings support for link editing to the rich-text editor. It allows for inserting hyperlinks into the edited content and offers the UI to create and edit them.
 
 ## Demo
 
@@ -27,13 +27,15 @@ CKEditor 5 allows for typing both at inner and outer boundaries of links to make
 
 ## Custom link attributes (decorators)
 
-By default, all links created in the editor have the `href="..."` attribute in the {@link builds/guides/integration/basic-api#getting-the-editor-data editor data}. If you want your links to have additional link attributes, {@link module:link/link~LinkConfig#decorators link decorators} provide an easy way to configure and manage them. There are two types of link decorators you can make use of:
+By default, all links created in the editor have the `href="..."` attribute in the {@link builds/guides/integration/basic-api#getting-the-editor-data editor data}. If you want your links to have additional link attributes, {@link module:link/link~LinkConfig#decorators link decorators} provide an easy way to configure and manage them.
 
-* [**automatic**](#adding-attributes-to-links-based-on-predefined-rules-automatic-decorators) – they match links against pre–defined rules and manage their attributes based on the results,
-* [**manual**](#adding-attributes-to-links-using-the-ui-manual-decorators) – they allow users to control link attributes individually using the editor UI.
+There are two types of link decorators you can use:
+
+* [**Automatic**](#adding-attributes-to-links-based-on-predefined-rules-automatic-decorators) – They match links against pre–defined rules and manage their attributes based on the results.
+* [**Manual**](#adding-attributes-to-links-using-the-ui-manual-decorators) – They allow users to control link attributes individually using the editor UI.
 
 <info-box>
-	Link decorators are disabled by default and it takes a proper [configuration](#configuration) to enable them in your editor. If you do not want to use them in your application, you do not need to do anything.
+	Link decorators are disabled by default and it takes a proper [configuration](#configuration) to enable them in your rich-text editor.
 </info-box>
 
 ### Demo
@@ -57,7 +59,7 @@ ClassicEditor
 			// Automatically add target="_blank" and rel="noopener noreferrer" to all external links.
 			addTargetToExternalLinks: true,
 
-			// Allow users control the "download" attribute of each link.
+			// Let the users control the "download" attribute of each link.
 			decorators: [
 				{
 					mode: 'manual',
@@ -75,15 +77,17 @@ ClassicEditor
 
 ### Configuration
 
-Decorators are configured via definitions in {@link module:link/link~LinkConfig#decorators `config.link.decorators`}. Each decorator definition must have its own unique name. In case of [manual decorators](#adding-attributes-to-links-using-the-ui-manual-decorators), that name also represents the decorator in the {@link framework/guides/architecture/editing-engine#text-attributes document model}.
+Decorators are configured through definitions provided in the {@link module:link/link~LinkConfig#decorators `config.link.decorators`} configuration option.
+
+Each decorator definition must have its own unique name. In case of [manual decorators](#adding-attributes-to-links-using-the-ui-manual-decorators), that name also represents the decorator in the {@link framework/guides/architecture/editing-engine#text-attributes document model}.
 
 <info-box warning>
-	Link decorators work independently and no conflict resolution mechanism exists. For example, configuring the `target` attribute using both an automatic and a manual decorator at a time could end up with quirky results. The same applies if multiple manual or automatic decorators were defined for the same attribute.
+	Link decorators work independently of one another and no conflict resolution mechanism exists. For example, configuring the `target` attribute using both an automatic and a manual decorator at the same time could end up with quirky results. The same applies if multiple manual or automatic decorators were defined for the same attribute.
 </info-box>
 
 #### Adding `target` and `rel` attributes to external links
 
-A very common use case for (automatic) link decorators is adding `target="_blank"` and `rel="noopener noreferrer"` attributes to all external links in the document. A dedicated {@link module:link/link~LinkConfig#addTargetToExternalLinks `config.link.addTargetToExternalLinks`} configuration has been created for that purpose. When this option is set `true`, all links starting with `http://`, `https://` or `//` are "decorated" with `target` and `rel` attributes.
+A very common use case for (automatic) link decorators is adding `target="_blank"` and `rel="noopener noreferrer"` attributes to all external links in the document. A dedicated {@link module:link/link~LinkConfig#addTargetToExternalLinks `config.link.addTargetToExternalLinks`} configuration has been created for that purpose. When this option is set to `true`, all links starting with `http://`, `https://` or `//` are "decorated" with `target` and `rel` attributes.
 
 ```js
 ClassicEditor
@@ -120,7 +124,7 @@ ClassicEditor
 	.catch( ... );
 ```
 
-**Note**: If you want to leave the decision whether a link should open in new tab to the users, do not use the `config.link.addTargetToExternalLinks` configuration but define a new [manual decorator](#adding-attributes-to-links-using-the-ui-manual-decorators) with the proper definition:
+If you want to leave the decision whether a link should open in a new tab to the users, do not use the `config.link.addTargetToExternalLinks` configuration but define a new [manual decorator](#adding-attributes-to-links-using-the-ui-manual-decorators) with the following definition instead:
 
 ```js
 ClassicEditor
@@ -130,7 +134,7 @@ ClassicEditor
 			decorators: {
 				addTargetToLinks: {
 					mode: 'manual',
-					label: 'Open link in a new tab',
+					label: 'Open in a new tab',
 					attributes: {
 						target: '_blank',
 						rel: 'noopener noreferrer'
@@ -145,7 +149,7 @@ ClassicEditor
 
 #### Adding attributes to links based on pre–defined rules (automatic decorators)
 
-Automatic link decorators match all links in the editor content against a {@link module:link/link~LinkDecoratorAutomaticDefinition function} which decides whether the link should gain some set of attributes or not, considering the URL (`href`) of the link. These decorators work silently being applied during {@link framework/guides/architecture/editing-engine#conversion data downcast} only.
+Automatic link decorators match all links in the editor content against a {@link module:link/link~LinkDecoratorAutomaticDefinition function} which decides whether the link should receive some set of attributes, considering the URL (`href`) of the link. These decorators work silently and are being applied during the {@link framework/guides/architecture/editing-engine#conversion data downcast} only.
 
 For instance, to create an automatic decorator that adds the `download="file.pdf"` attribute to all links ending with the `".pdf"` extension, you should add the following {@link module:link/link~LinkDecoratorAutomaticDefinition definition} to {@link module:link/link~LinkConfig#decorators `config.link.decorators`}:
 
@@ -170,12 +174,12 @@ ClassicEditor
 ```
 
 <info-box>
-	If you want `target` and `rel` attributes to be added to all external links in your content, we prepared a [dedicated configuration](#adding-target-and-rel-attributes-to-external-links) exactly for that purpose so you do not have to define the automatic decorator by yourself.
+	If you want the `target` and `rel` attributes to be added to all external links in your content, we prepared a [dedicated configuration](#adding-target-and-rel-attributes-to-external-links) exactly for that purpose so you do not have to define the automatic decorator by yourself.
 </info-box>
 
 #### Adding attributes to links using the UI (manual decorators)
 
-Manual link decorators are represented in the link editing balloon as switch buttons users can use to control the presence of attributes of a particular link (check out the [demo](#demo) to learn more). Each manual decorator {@link module:link/link~LinkDecoratorManualDefinition definition} contains a human–readable label displayed next to the switch button in the link editing balloon. Make sure it is compact and precise for the convenience of the users.
+Manual link decorators are represented in the link editing balloon as switch buttons that the users can use to control the presence of attributes of a particular link (check out the [demo](#demo) to learn more). Each manual decorator {@link module:link/link~LinkDecoratorManualDefinition definition} contains a human–readable label displayed next to the switch button in the link editing balloon. Make sure it is compact and precise for the convenience of the users.
 
 To configure a "Downloadable" switch button in the link editing balloon that adds the `download="file"` attribute to the link when turned on, add the following definition to {@link module:link/link~LinkConfig#decorators `config.link.decorators`}:
 
@@ -246,7 +250,7 @@ editor.execute( 'link', 'http://example.com', { linkIsExternal: true } );
 editor.execute( 'unlink' );
 ```
 
-Links are represented in the {@link module:engine/model/model~Model model} using the `linkHref` attribute. [Manual link decorators](#adding-attributes-to-links-using-the-ui-manual-decorators) are represented in the model using text attributes corresponding to their names as configured in {@link module:link/link~LinkConfig#decorators `config.link.decorators`}.
+Links are represented in the {@link module:engine/model/model~Model model} using the `linkHref` attribute. [Manual link decorators](#adding-attributes-to-links-using-the-ui-manual-decorators) are represented in the model using text attributes corresponding to their names, as configured in {@link module:link/link~LinkConfig#decorators `config.link.decorators`}.
 
 <info-box>
 	We recommend using the official {@link framework/guides/development-tools#ckeditor-5-inspector CKEditor 5 inspector} for development and debugging. It will give you tons of useful information about the state of the editor such as internal data structures, selection, commands, and many more.

+ 29 - 30
packages/ckeditor5-link/src/link.js

@@ -14,7 +14,7 @@ import LinkUI from './linkui';
 /**
  * The link plugin.
  *
- * This is a "glue" plugin which loads the {@link module:link/linkediting~LinkEditing link editing feature}
+ * This is a "glue" plugin that loads the {@link module:link/linkediting~LinkEditing link editing feature}
  * and {@link module:link/linkui~LinkUI link UI feature}.
  *
  * @extends module:core/plugin~Plugin
@@ -58,8 +58,8 @@ export default class Link extends Plugin {
  */
 
 /**
- * When set `true`, the `target="_blank"` and `rel="noopener noreferrer"` attributes are automatically added to all external links
- * in the editor. By external are meant all links in the editor content starting with `http`, `https`, or `//`.
+ * When set to `true`, the `target="blank"` and `rel="noopener noreferrer"` attributes are automatically added to all external links
+ * in the editor. "External links" are all links in the editor content starting with `http`, `https`, or `//`.
  *
  *		ClassicEditor
  *			.create( editorElement, {
@@ -70,15 +70,15 @@ export default class Link extends Plugin {
  *			.then( ... )
  *			.catch( ... );
  *
- * Internally, this option activates a predefined {@link module:link/link~LinkConfig#decorators automatic link decorator},
- * which extends all external links with the `target` and `rel` attributes without additional configuration.
+ * Internally, this option activates a predefined {@link module:link/link~LinkConfig#decorators automatic link decorator}
+ * that extends all external links with the `target` and `rel` attributes.
  *
  * **Note**: To control the `target` and `rel` attributes of specific links in the edited content, a dedicated
  * {@link module:link/link~LinkDecoratorManualDefinition manual} decorator must be defined in the
  * {@link module:link/link~LinkConfig#decorators `config.link.decorators`} array. In such scenario,
  * the `config.link.addTargetToExternalLinks` option should remain `undefined` or `false` to not interfere with the manual decorator.
  *
- * **Note**: It is possible to add other {@link module:link/link~LinkDecoratorAutomaticDefinition automatic}
+ * It is possible to add other {@link module:link/link~LinkDecoratorAutomaticDefinition automatic}
  * or {@link module:link/link~LinkDecoratorManualDefinition manual} link decorators when this option is active.
  *
  * More information about decorators can be found in the {@link module:link/link~LinkConfig#decorators decorators configuration}
@@ -92,12 +92,12 @@ export default class Link extends Plugin {
  * Decorators provide an easy way to configure and manage additional link attributes in the editor content. There are
  * two types of link decorators:
  *
- * * {@link module:link/link~LinkDecoratorAutomaticDefinition automatic} – they match links against pre–defined rules and
- * manage their attributes based on the results,
- * * {@link module:link/link~LinkDecoratorManualDefinition manual} – they allow users to control link attributes individually
+ * * {@link module:link/link~LinkDecoratorAutomaticDefinition Automatic} &ndash; They match links against pre–defined rules and
+ * manage their attributes based on the results.
+ * * {@link module:link/link~LinkDecoratorManualDefinition Manual} &ndash; They allow users to control link attributes individually,
  *  using the editor UI.
  *
- * Link decorators are defined as an object with key-value pairs, where the key is a name provided for a given decorator and the
+ * Link decorators are defined as objects with key-value pairs, where the key is the name provided for a given decorator and the
  * value is the decorator definition.
  *
  * The name of the decorator also corresponds to the {@glink framework/guides/architecture/editing-engine#text-attributes text attribute}
@@ -132,8 +132,8 @@ export default class Link extends Plugin {
  * To learn more about the configuration syntax, check out the {@link module:link/link~LinkDecoratorAutomaticDefinition automatic}
  * and {@link module:link/link~LinkDecoratorManualDefinition manual} decorator option reference.
  *
- * **Warning:** Currently, link decorators work independently and no conflict resolution mechanism exists.
- * For example, configuring the `target` attribute using both an automatic and a manual decorator at a time could end up with
+ * **Warning:** Currently, link decorators work independently of one another and no conflict resolution mechanism exists.
+ * For example, configuring the `target` attribute using both an automatic and a manual decorator at the same time could end up with
  * quirky results. The same applies if multiple manual or automatic decorators were defined for the same attribute.
  *
  * **Note**: Since the `target` attribute management for external links is a common use case, there is a predefined automatic decorator
@@ -141,7 +141,7 @@ export default class Link extends Plugin {
  * {@link module:link/link~LinkConfig#addTargetToExternalLinks `config.link.addTargetToExternalLinks`}
  * configuration description to learn more.
  *
- * See also {@glink features/link#custom-link-attributes-decorators link's feature} guide for more information.
+ * See also the {@glink features/link#custom-link-attributes-decorators link feature guide} for more information.
  *
  * @member {Object.<String, module:link/link~LinkDecoratorDefinition>} module:link/link~LinkConfig#decorators
  */
@@ -154,23 +154,22 @@ export default class Link extends Plugin {
  */
 
 /**
- * The kind of the decorator.
+ * Link decorator type.
  *
- * Check out the {@glink features/link#custom-link-attributes-decorators link feature} guide for more information.
+ * Check out the {@glink features/link#custom-link-attributes-decorators link feature guide} for more information.
  *
  * @member {'manual'|'automatic'} module:link/link~LinkDecoratorDefinition#mode
  */
 
 /**
- * Describes an automatic link {@link module:link/link~LinkConfig#decorators decorator}. This kind of a decorator matches
- * all links in the editor content against a function which decides whether the link should gain a pre–defined set of attributes
- * or not.
+ * Describes an automatic {@link module:link/link~LinkConfig#decorators link decorator}. This decorator type matches
+ * all links in the editor content against a function that decides whether the link should receive a pre–defined set of attributes.
  *
- * It takes an object with key-value pairs of attributes and a callback function which must return a boolean based on link's
+ * It takes an object with key-value pairs of attributes and a callback function that must return a Boolean value based on the link's
  * `href` (URL). When the callback returns `true`, attributes are applied to the link.
  *
- * For example, to add the `target="_blank"` attribute to all links in the editor starting with the `http://`,
- * then configuration could look like this:
+ * For example, to add the `target="_blank"` attribute to all links in the editor starting with `http://`, the
+ * configuration could look like this:
  *
  *		{
  *			mode: 'automatic',
@@ -181,24 +180,24 @@ export default class Link extends Plugin {
  *		}
  *
  * **Note**: Since the `target` attribute management for external links is a common use case, there is a predefined automatic decorator
- * dedicated for that purpose which can be enabled by turning a single option on. Check out the
+ * dedicated for that purpose that can be enabled by turning a single option on. Check out the
  * {@link module:link/link~LinkConfig#addTargetToExternalLinks `config.link.addTargetToExternalLinks`}
  * configuration description to learn more.
  *
  * @typedef {Object} module:link/link~LinkDecoratorAutomaticDefinition
- * @property {'automatic'} mode The kind of the decorator. `'automatic'` for all automatic decorators.
- * @property {Function} callback Takes an `url` as a parameter and returns `true` if the `attributes` should be applied to the link.
+ * @property {'automatic'} mode Link decorator type. It is `'automatic'` for all automatic decorators.
+ * @property {Function} callback Takes a `url` as a parameter and returns `true` if the `attributes` should be applied to the link.
  * @property {Object} attributes Key-value pairs used as link attributes added to the output during the
  * {@glink framework/guides/architecture/editing-engine#conversion downcasting}.
  * Attributes should follow the {@link module:engine/view/elementdefinition~ElementDefinition} syntax.
  */
 
 /**
- * Describes a manual link {@link module:link/link~LinkConfig#decorators decorator}. This kind of a decorator is represented in
- * the link feature's {@link module:link/linkui user interface} as a switch the user can use to control the presence
- * of a predefined set of attributes.
+ * Describes a manual {@link module:link/link~LinkConfig#decorators link decorator}. This decorator type is represented in
+ * the link feature's {@link module:link/linkui user interface} as a switch that the user can use to control the presence
+ * of a predefined set of attributes.
  *
- * For instance, to allow users to manually control the presence of the `target="_blank"` and
+ * For instance, to allow the users to manually control the presence of the `target="_blank"` and
  * `rel="noopener noreferrer"` attributes on specific links, the decorator could look as follows:
  *
  *		{
@@ -211,8 +210,8 @@ export default class Link extends Plugin {
  *		}
  *
  * @typedef {Object} module:link/link~LinkDecoratorManualDefinition
- * @property {'manual'} mode The kind of the decorator. `'manual'` for all manual decorators.
- * @property {String} label The label of the UI button the user can use to control the presence of link attributes.
+ * @property {'manual'} mode Link decorator type. It is `'manual'` for all manual decorators.
+ * @property {String} label The label of the UI button that the user can use to control the presence of link attributes.
  * @property {Object} attributes Key-value pairs used as link attributes added to the output during the
  * {@glink framework/guides/architecture/editing-engine#conversion downcasting}.
  * Attributes should follow the {@link module:engine/view/elementdefinition~ElementDefinition} syntax.

+ 14 - 14
packages/ckeditor5-link/src/linkcommand.js

@@ -33,7 +33,7 @@ export default class LinkCommand extends Command {
 		 * A collection of {@link module:link/utils~ManualDecorator manual decorators}
 		 * corresponding to the {@link module:link/link~LinkConfig#decorators decorator configuration}.
 		 *
-		 * You can consider it a model with states of manual decorators added to currently selected link.
+		 * You can consider it a model with states of manual decorators added to the currently selected link.
 		 *
 		 * @readonly
 		 * @type {module:utils/collection~Collection}
@@ -42,7 +42,7 @@ export default class LinkCommand extends Command {
 	}
 
 	/**
-	 * Synchronize state of {@link #manualDecorators} with actually present elements in the model.
+	 * Synchronizes the state of {@link #manualDecorators} with the currently present elements in the model.
 	 */
 	restoreManualDecoratorStates() {
 		for ( const manualDecorator of this.manualDecorators ) {
@@ -72,8 +72,8 @@ export default class LinkCommand extends Command {
 	 * When the selection is non-collapsed, the `linkHref` attribute will be applied to nodes inside the selection, but only to
 	 * those nodes where the `linkHref` attribute is allowed (disallowed nodes will be omitted).
 	 *
-	 * When the selection is collapsed and is not inside the text with the `linkHref` attribute, the
-	 * new {@link module:engine/model/text~Text Text node} with the `linkHref` attribute will be inserted in place of caret, but
+	 * When the selection is collapsed and is not inside the text with the `linkHref` attribute, a
+	 * new {@link module:engine/model/text~Text text node} with the `linkHref` attribute will be inserted in place of the caret, but
 	 * only if such element is allowed in this place. The `_data` of the inserted text will equal the `href` parameter.
 	 * The selection will be updated to wrap the just inserted text node.
 	 *
@@ -81,18 +81,18 @@ export default class LinkCommand extends Command {
 	 *
 	 * # Decorators and model attribute management
 	 *
-	 * There is an optional argument to this command, which applies or removes model
+	 * There is an optional argument to this command that applies or removes model
 	 * {@glink framework/guides/architecture/editing-engine#text-attributes text attributes} brought by
 	 * {@link module:link/utils~ManualDecorator manual link decorators}.
 	 *
 	 * Text attribute names in the model correspond to the entries in the {@link module:link/link~LinkConfig#decorators configuration}.
 	 * For every decorator configured, a model text attribute exists with the "link" prefix. For example, a `'linkMyDecorator'` attribute
-	 * corresponds to the `'myDecorator'` in the configuration.
+	 * corresponds to `'myDecorator'` in the configuration.
 	 *
 	 * To learn more about link decorators, check out the {@link module:link/link~LinkConfig#decorators `config.link.decorators`}
 	 * documentation.
 	 *
-	 * Here is how to manage decorator attributes via the link command:
+	 * Here is how to manage decorator attributes with the link command:
 	 *
 	 *		const linkCommand = editor.commands.get( 'link' );
 	 *
@@ -101,25 +101,25 @@ export default class LinkCommand extends Command {
 	 *			linkIsExternal: true
 	 *		} );
 	 *
-	 *		// Removing a decorator attribute from a selection.
+	 *		// Removing a decorator attribute from the selection.
 	 *		linkCommand.execute( 'http://example.com', {
 	 *			linkIsExternal: false
 	 *		} );
 	 *
-	 *		// Adding multiple decorator attributes at a time.
+	 *		// Adding multiple decorator attributes at the same time.
 	 *		linkCommand.execute( 'http://example.com', {
 	 *			linkIsExternal: true,
 	 *			linkIsDownloadable: true,
 	 *		} );
 	 *
-	 *		// Removing and adding decorator attributes at a time.
+	 *		// Removing and adding decorator attributes at the same time.
 	 *		linkCommand.execute( 'http://example.com', {
 	 *			linkIsExternal: false,
 	 *			linkFoo: true,
 	 *			linkIsDownloadable: false,
 	 *		} );
 	 *
-	 * **Note**: If decorator attribute name is not specified its state remains untouched.
+	 * **Note**: If the decorator attribute name is not specified, its state remains untouched.
 	 *
 	 * **Note**: {@link module:link/unlinkcommand~UnlinkCommand#execute `UnlinkCommand#execute()`} removes all
 	 * decorator attributes.
@@ -206,11 +206,11 @@ export default class LinkCommand extends Command {
 	}
 
 	/**
-	 * Method provides the information if a decorator with given name is present in currently processed selection.
+	 * Provides information whether a decorator with a given name is present in the currently processed selection.
 	 *
 	 * @private
-	 * @param {String} decoratorName name of a manual decorator used in the model
-	 * @returns {Boolean} The information if a given decorator is currently present in a selection
+	 * @param {String} decoratorName The name of the manual decorator used in the model
+	 * @returns {Boolean} The information whether a given decorator is currently present in the selection.
 	 */
 	_getDecoratorStateFromModel( decoratorName ) {
 		const doc = this.editor.model.document;

+ 10 - 10
packages/ckeditor5-link/src/linkediting.js

@@ -102,7 +102,7 @@ export default class LinkEditing extends Plugin {
 	 * for each one of them. Downcast dispatchers are obtained using the
 	 * {@link module:link/utils~AutomaticDecorators#getDispatcher} method.
 	 *
-	 * **Note**: This method also activates the automatic external link decorator if enabled via
+	 * **Note**: This method also activates the automatic external link decorator if enabled with
 	 * {@link module:link/link~LinkConfig#addTargetToExternalLinks `config.link.addTargetToExternalLinks`}.
 	 *
 	 * @private
@@ -112,7 +112,7 @@ export default class LinkEditing extends Plugin {
 		const editor = this.editor;
 		const automaticDecorators = new AutomaticDecorators();
 
-		// Adds default decorator for external links.
+		// Adds a default decorator for external links.
 		if ( editor.config.get( 'link.addTargetToExternalLinks' ) ) {
 			automaticDecorators.add( {
 				id: 'linkIsExternal',
@@ -133,11 +133,11 @@ export default class LinkEditing extends Plugin {
 	}
 
 	/**
-	 * Processes an array of configured {@link module:link/link~LinkDecoratorManualDefinition manual decorators}
-	 * and transforms them into {@link module:link/utils~ManualDecorator} instances and stores them in the
+	 * Processes an array of configured {@link module:link/link~LinkDecoratorManualDefinition manual decorators},
+	 * transforms them into {@link module:link/utils~ManualDecorator} instances and stores them in the
 	 * {@link module:link/linkcommand~LinkCommand#manualDecorators} collection (a model for manual decorators state).
 	 *
-	 * Also registers an {@link module:engine/conversion/downcasthelpers~DowncastHelpers#attributeToElement attributeToElement}
+	 * Also registers an {@link module:engine/conversion/downcasthelpers~DowncastHelpers#attributeToElement attribute-to-element}
 	 * converter for each manual decorator and extends the {@link module:engine/model/schema~Schema model's schema}
 	 * with adequate model attributes.
 	 *
@@ -187,13 +187,13 @@ export default class LinkEditing extends Plugin {
 	 * Adds a visual highlight style to a link in which the selection is anchored.
 	 * Together with two-step caret movement, they indicate that the user is typing inside the link.
 	 *
-	 * Highlight is turned on by adding `.ck-link_selected` class to the link in the view:
+	 * Highlight is turned on by adding the `.ck-link_selected` class to the link in the view:
 	 *
-	 * * the class is removed before conversion has started, as callbacks added with `'highest'` priority
-	 * to {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher} events,
-	 * * the class is added in the view post fixer, after other changes in the model tree were converted to the view.
+	 * * The class is removed before the conversion has started, as callbacks added with the `'highest'` priority
+	 * to {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher} events.
+	 * * The class is added in the view post fixer, after other changes in the model tree were converted to the view.
 	 *
-	 * This way, adding and removing highlight does not interfere with conversion.
+	 * This way, adding and removing the highlight does not interfere with conversion.
 	 *
 	 * @private
 	 */

+ 15 - 15
packages/ckeditor5-link/src/linkui.js

@@ -138,7 +138,7 @@ export default class LinkUI extends Plugin {
 	 * Creates the {@link module:link/ui/linkformview~LinkFormView} instance.
 	 *
 	 * @private
-	 * @returns {module:link/ui/linkformview~LinkFormView} The link form instance.
+	 * @returns {module:link/ui/linkformview~LinkFormView} The link form view instance.
 	 */
 	_createFormView() {
 		const editor = this.editor;
@@ -313,19 +313,19 @@ export default class LinkUI extends Plugin {
 	}
 
 	/**
-	 * Closes form view. Decides whether the balloon should be hidden completely or if action view should be shown. This is decided upon
-	 * link command value (which has value if the document selection is in link).
+	 * Closes the form view. Decides whether the balloon should be hidden completely or if the action view should be shown. This is
+	 * decided upon the link command value (which has a value if the document selection is in the link).
 	 *
-	 * If there are defined {@link module:link/link~LinkConfig#decorators} in editor's config, then there are additionally
-	 * rest switch buttons state responsible for manual decorators handling.
+	 * Additionally, if any {@link module:link/link~LinkConfig#decorators} are defined in the editor configuration, the state of
+	 * switch buttons responsible for manual decorator handling is restored.
 	 *
 	 * @private
 	 */
 	_closeFormView() {
 		const linkCommand = this.editor.commands.get( 'link' );
 
-		// Reset manual decorator states to represent current model state. This case is important to reset switch buttons,
-		// when user cancel editing form.
+		// Restore manual decorator states to represent the current model state. This case is important to reset the switch buttons
+		// when the user cancels the editing form.
 		linkCommand.restoreManualDecoratorStates();
 
 		if ( linkCommand.value !== undefined ) {
@@ -355,7 +355,7 @@ export default class LinkUI extends Plugin {
 	}
 
 	/**
-	 * Shows the right kind of the UI for current state of the command. It's either
+	 * Shows the correct UI type for the current state of the command. It is either
 	 * {@link #formView} or {@link #actionsView}.
 	 *
 	 * @param {Boolean} forceVisible
@@ -431,7 +431,7 @@ export default class LinkUI extends Plugin {
 
 	/**
 	 * Makes the UI react to the {@link module:core/editor/editorui~EditorUI#event:update} event to
-	 * reposition itself when the editor ui should be refreshed.
+	 * reposition itself when the editor UI should be refreshed.
 	 *
 	 * See: {@link #_hideUI} to learn when the UI stops reacting to the `update` event.
 	 *
@@ -488,7 +488,7 @@ export default class LinkUI extends Plugin {
 	}
 
 	/**
-	 * Returns true when {@link #formView} is in the {@link #_balloon}.
+	 * Returns `true` when {@link #formView} is in the {@link #_balloon}.
 	 *
 	 * @readonly
 	 * @protected
@@ -499,7 +499,7 @@ export default class LinkUI extends Plugin {
 	}
 
 	/**
-	 * Returns true when {@link #actionsView} is in the {@link #_balloon}.
+	 * Returns `true` when {@link #actionsView} is in the {@link #_balloon}.
 	 *
 	 * @readonly
 	 * @protected
@@ -510,7 +510,7 @@ export default class LinkUI extends Plugin {
 	}
 
 	/**
-	 * Returns true when {@link #actionsView} is in the {@link #_balloon} and it is
+	 * Returns `true` when {@link #actionsView} is in the {@link #_balloon} and it is
 	 * currently visible.
 	 *
 	 * @readonly
@@ -522,7 +522,7 @@ export default class LinkUI extends Plugin {
 	}
 
 	/**
-	 * Returns true when {@link #actionsView} or {@link #formView} is in the {@link #_balloon}.
+	 * Returns `true` when {@link #actionsView} or {@link #formView} is in the {@link #_balloon}.
 	 *
 	 * @readonly
 	 * @protected
@@ -533,7 +533,7 @@ export default class LinkUI extends Plugin {
 	}
 
 	/**
-	 * Returns true when {@link #actionsView} or {@link #formView} is in the {@link #_balloon} and it is
+	 * Returns `true` when {@link #actionsView} or {@link #formView} is in the {@link #_balloon} and it is
 	 * currently visible.
 	 *
 	 * @readonly
@@ -575,7 +575,7 @@ export default class LinkUI extends Plugin {
 	 * the {@link module:engine/view/document~Document editing view's} selection or `null`
 	 * if there is none.
 	 *
-	 * **Note**: For a non–collapsed selection the link element is only returned when **fully**
+	 * **Note**: For a non–collapsed selection, the link element is only returned when **fully**
 	 * selected and the **only** element within the selection boundaries.
 	 *
 	 * @private

+ 4 - 4
packages/ckeditor5-link/src/ui/linkactionsview.js

@@ -23,7 +23,7 @@ import pencilIcon from '@ckeditor/ckeditor5-core/theme/icons/pencil.svg';
 import '../../theme/linkactions.css';
 
 /**
- * The link actions view class. This view displays link preview, allows
+ * The link actions view class. This view displays the link preview, allows
  * unlinking or editing the link.
  *
  * @extends module:ui/view~View
@@ -75,7 +75,7 @@ export default class LinkActionsView extends View {
 		this.editButtonView = this._createButton( t( 'Edit link' ), pencilIcon, 'edit' );
 
 		/**
-		 * Value of the "href" attribute of the link to use in the {@link #previewButtonView}.
+		 * The value of the "href" attribute of the link to use in the {@link #previewButtonView}.
 		 *
 		 * @observable
 		 * @member {String}
@@ -83,7 +83,7 @@ export default class LinkActionsView extends View {
 		this.set( 'href' );
 
 		/**
-		 * A collection of views which can be focused in the view.
+		 * A collection of views that can be focused in the view.
 		 *
 		 * @readonly
 		 * @protected
@@ -168,7 +168,7 @@ export default class LinkActionsView extends View {
 	 *
 	 * @private
 	 * @param {String} label The button label.
-	 * @param {String} icon The button's icon.
+	 * @param {String} icon The button icon.
 	 * @param {String} [eventName] An event name that the `ButtonView#execute` event will be delegated to.
 	 * @returns {module:ui/button/buttonview~ButtonView} The button view instance.
 	 */

+ 14 - 14
packages/ckeditor5-link/src/ui/linkformview.js

@@ -96,7 +96,7 @@ export default class LinkFormView extends View {
 		this._manualDecoratorSwitches = this._createManualDecoratorSwitches( manualDecorators );
 
 		/**
-		 * Collection of child views in the form.
+		 * A collection of child views in the form.
 		 *
 		 * @readonly
 		 * @type {module:ui/viewcollection~ViewCollection}
@@ -104,7 +104,7 @@ export default class LinkFormView extends View {
 		this.children = this._createFormChildren( manualDecorators );
 
 		/**
-		 * A collection of views which can be focused in the form.
+		 * A collection of views that can be focused in the form.
 		 *
 		 * @readonly
 		 * @protected
@@ -157,7 +157,7 @@ export default class LinkFormView extends View {
 	 * {@link module:link/linkcommand~LinkCommand#manualDecorators manual link decorators}
 	 * in the {@link module:link/ui/linkformview~LinkFormView}.
 	 *
-	 * @returns {Object.<String,Boolean>} key-value pairs, where the key is the name of the decorator and the value is
+	 * @returns {Object.<String,Boolean>} Key-value pairs, where the key is the name of the decorator and the value is
 	 * its state.
 	 */
 	getDecoratorSwitchesState() {
@@ -225,7 +225,7 @@ export default class LinkFormView extends View {
 	 *
 	 * @private
 	 * @param {String} label The button label.
-	 * @param {String} icon The button's icon.
+	 * @param {String} icon The button icon.
 	 * @param {String} className The additional button CSS class name.
 	 * @param {String} [eventName] An event name that the `ButtonView#execute` event will be delegated to.
 	 * @returns {module:ui/button/buttonview~ButtonView} The button view instance.
@@ -254,12 +254,12 @@ export default class LinkFormView extends View {
 
 	/**
 	 * Populates {@link module:ui/viewcollection~ViewCollection} of {@link module:ui/button/switchbuttonview~SwitchButtonView}
-	 * made based on {@link module:link/linkcommand~LinkCommand#manualDecorators}
+	 * made based on {@link module:link/linkcommand~LinkCommand#manualDecorators}.
 	 *
 	 * @private
 	 * @param {module:utils/collection~Collection} manualDecorators A reference to the
-	 * collection of manual decorators stored in link's command.
-	 * @returns {module:ui/viewcollection~ViewCollection} of Switch Buttons.
+	 * collection of manual decorators stored in the link command.
+	 * @returns {module:ui/viewcollection~ViewCollection} of switch buttons.
 	 */
 	_createManualDecoratorSwitches( manualDecorators ) {
 		const switches = this.createCollection();
@@ -288,14 +288,14 @@ export default class LinkFormView extends View {
 	/**
 	 * Populates the {@link #children} collection of the form.
 	 *
-	 * If {@link module:link/linkcommand~LinkCommand#manualDecorators manual decorators} are configured in the editor, creates an
+	 * If {@link module:link/linkcommand~LinkCommand#manualDecorators manual decorators} are configured in the editor, it creates an
 	 * additional `View` wrapping all {@link #_manualDecoratorSwitches} switch buttons corresponding
-	 * to those decorators.
+	 * to these decorators.
 	 *
 	 * @private
-	 * @param {module:utils/collection~Collection} manualDecorators A reference to the
-	 * collection of manual decorators stored in link's command.
-	 * @returns {module:ui/viewcollection~ViewCollection} children of LinkFormView.
+	 * @param {module:utils/collection~Collection} manualDecorators A reference to
+	 * the collection of manual decorators stored in the link command.
+	 * @returns {module:ui/viewcollection~ViewCollection} The children of link form view.
 	 */
 	_createFormChildren( manualDecorators ) {
 		const children = this.createCollection();
@@ -337,13 +337,13 @@ export default class LinkFormView extends View {
 
 /**
  * Fired when the form view is submitted (when one of the children triggered the submit event),
- * e.g. click on {@link #saveButtonView}.
+ * for example with a click on {@link #saveButtonView}.
  *
  * @event submit
  */
 
 /**
- * Fired when the form view is canceled, e.g. click on {@link #cancelButtonView}.
+ * Fired when the form view is canceled, for example with a click on {@link #cancelButtonView}.
  *
  * @event cancel
  */

+ 2 - 2
packages/ckeditor5-link/src/unlinkcommand.js

@@ -26,8 +26,8 @@ export default class UnlinkCommand extends Command {
 	/**
 	 * Executes the command.
 	 *
-	 * When the selection is collapsed, removes the `linkHref` attribute from each node with the same `linkHref` attribute value.
-	 * When the selection is non-collapsed, removes the `linkHref` attribute from each node in selected ranges.
+	 * When the selection is collapsed, it removes the `linkHref` attribute from each node with the same `linkHref` attribute value.
+	 * When the selection is non-collapsed, it removes the `linkHref` attribute from each node in selected ranges.
 	 *
 	 * # Decorators
 	 *

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

@@ -23,7 +23,7 @@ export function isLinkElement( node ) {
 }
 
 /**
- * Creates link {@link module:engine/view/attributeelement~AttributeElement} with provided `href` attribute.
+ * Creates link {@link module:engine/view/attributeelement~AttributeElement} with the provided `href` attribute.
  *
  * @param {String} href
  * @returns {module:engine/view/attributeelement~AttributeElement}
@@ -39,9 +39,9 @@ export function createLinkElement( href, writer ) {
 /**
  * Returns a safe URL based on a given value.
  *
- * An URL is considered safe if it is safe for the user (does not contain any malicious code).
+ * A URL is considered safe if it is safe for the user (does not contain any malicious code).
  *
- * If URL is considered unsafe, a simple `"#"` is returned.
+ * If a URL is considered unsafe, a simple `"#"` is returned.
  *
  * @protected
  * @param {*} url
@@ -63,16 +63,16 @@ function isSafeUrl( url ) {
 }
 
 /**
- * Returns {@link module:link/link~LinkConfig#decorators `config.link.decorators`} configuration processed
- * to respect the locale of the editor, i.e. to display {@link module:link/link~LinkDecoratorManualDefinition label}
+ * Returns the {@link module:link/link~LinkConfig#decorators `config.link.decorators`} configuration processed
+ * to respect the locale of the editor, i.e. to display the {@link module:link/link~LinkDecoratorManualDefinition label}
  * in the correct language.
  *
  * **Note**: Only the few most commonly used labels are translated automatically. Other labels should be manually
  * translated in the {@link module:link/link~LinkConfig#decorators `config.link.decorators`} configuration.
  *
  * @param {module:utils/locale~Locale#t} t shorthand for {@link module:utils/locale~Locale#t Locale#t}
- * @param {Array.<module:link/link~LinkDecoratorDefinition>} decorators reference
- * where labels' values should be localized.
+ * @param {Array.<module:link/link~LinkDecoratorDefinition>} The decorator reference
+ * where the label values should be localized.
  * @returns {Array.<module:link/link~LinkDecoratorDefinition>}
  */
 export function getLocalizedDecorators( t, decorators ) {
@@ -92,8 +92,8 @@ export function getLocalizedDecorators( t, decorators ) {
 }
 
 /**
- * Converts an object with defined decorators to a normalized array of decorators. There is also added `id` key for each decorator,
- * which is used as attribute's name in the model.
+ * Converts an object with defined decorators to a normalized array of decorators. The `id` key is added for each decorator and
+ * is used as the attribute's name in the model.
  *
  * @param {Object.<String, module:link/link~LinkDecoratorDefinition>} decorators
  * @returns {Array.<module:link/link~LinkDecoratorDefinition>}

+ 9 - 9
packages/ckeditor5-link/src/utils/automaticdecorators.js

@@ -8,14 +8,14 @@
  */
 
 /**
- * Helper class which tight together all {@link module:link/link~LinkDecoratorAutomaticDefinition} and provides
+ * Helper class that ties together all {@link module:link/link~LinkDecoratorAutomaticDefinition} and provides
  * a {@link module:engine/conversion/downcasthelpers~DowncastHelpers#attributeToElement downcast dispatcher} for them.
  */
 export default class AutomaticDecorators {
 	constructor() {
 		/**
-		 * Stores definition of {@link module:link/link~LinkDecoratorAutomaticDefinition automatic decorators}.
-		 * Those data are used as source for a downcast dispatcher to make proper conversion to output data.
+		 * Stores the definition of {@link module:link/link~LinkDecoratorAutomaticDefinition automatic decorators}.
+		 * This data is used as a source for a downcast dispatcher to create a proper conversion to output data.
 		 *
 		 * @private
 		 * @type {Set}
@@ -24,7 +24,7 @@ export default class AutomaticDecorators {
 	}
 
 	/**
-	 * Gives information how many decorators is stored in {@link module:link/utils~AutomaticDecorators} instance.
+	 * Gives information about the number of decorators stored in the {@link module:link/utils~AutomaticDecorators} instance.
 	 *
 	 * @readonly
 	 * @protected
@@ -35,10 +35,10 @@ export default class AutomaticDecorators {
 	}
 
 	/**
-	 * Add automatic decorator objects or array with them to be used during downcasting.
+	 * Adds automatic decorator objects or an array with them to be used during downcasting.
 	 *
 	 * @param {module:link/link~LinkDecoratorAutomaticDefinition|Array.<module:link/link~LinkDecoratorAutomaticDefinition>} item
-	 * configuration object of automatic rules for decorating links. It might be also array of such objects.
+	 * A configuration object of automatic rules for decorating links. It might also be an array of such objects.
 	 */
 	add( item ) {
 		if ( Array.isArray( item ) ) {
@@ -49,10 +49,10 @@ export default class AutomaticDecorators {
 	}
 
 	/**
-	 * Provides the conversion helper used in an {@link module:engine/conversion/downcasthelpers~DowncastHelpers#add} method.
+	 * Provides the conversion helper used in the {@link module:engine/conversion/downcasthelpers~DowncastHelpers#add} method.
 	 *
-	 * @returns {Function} dispatcher function used as conversion helper
-	 * in {@link module:engine/conversion/downcasthelpers~DowncastHelpers#add}
+	 * @returns {Function} A dispatcher function used as conversion helper
+	 * in {@link module:engine/conversion/downcasthelpers~DowncastHelpers#add}.
 	 */
 	getDispatcher() {
 		return dispatcher => {

+ 12 - 12
packages/ckeditor5-link/src/utils/manualdecorator.js

@@ -11,33 +11,33 @@ import ObservableMixin from '@ckeditor/ckeditor5-utils/src/observablemixin';
 import mix from '@ckeditor/ckeditor5-utils/src/mix';
 
 /**
- * Helper class which stores manual decorators with observable {@link module:link/utils~ManualDecorator#value}
- * to support integration with the UI state. An instance of this class is a model with state of single manual decorators.
+ * Helper class that stores manual decorators with observable {@link module:link/utils~ManualDecorator#value}
+ * to support integration with the UI state. An instance of this class is a model with the state of individual manual decorators.
  * These decorators are kept as collections in {@link module:link/linkcommand~LinkCommand#manualDecorators}.
  *
  * @mixes module:utils/observablemixin~ObservableMixin
  */
 export default class ManualDecorator {
 	/**
-	 * Creates new instance of {@link module:link/utils~ManualDecorator}.
+	 * Creates a new instance of {@link module:link/utils~ManualDecorator}.
 	 *
 	 * @param {Object} config
-	 * @param {String} config.id name of attribute used in model, which represents given manual decorator.
-	 * For example `'linkIsExternal'`.
-	 * @param {String} config.label The label used in user interface to toggle manual decorator.
-	 * @param {Object} config.attributes Set of attributes added to output data, when decorator is active for specific link.
-	 * Attributes should keep format of attributes defined in {@link module:engine/view/elementdefinition~ElementDefinition}.
+	 * @param {String} config.id The name of the attribute used in the model that represents a given manual decorator.
+	 * For example: `'linkIsExternal'`.
+	 * @param {String} config.label The label used in the user interface to toggle the manual decorator.
+	 * @param {Object} config.attributes A set of attributes added to output data when the decorator is active for a specific link.
+	 * Attributes should keep the format of attributes defined in {@link module:engine/view/elementdefinition~ElementDefinition}.
 	 */
 	constructor( { id, label, attributes } ) {
 		/**
-		 * Id of manual decorator, which is a name of attribute in model, for example 'linkManualDecorator0'.
+		 * An ID of a manual decorator which is the name of the attribute in the model, for example: 'linkManualDecorator0'.
 		 *
 		 * @type {String}
 		 */
 		this.id = id;
 
 		/**
-		 * Value of current manual decorator. It reflects its state from UI.
+		 * The value of the current manual decorator. It reflects its state from the UI.
 		 *
 		 * @observable
 		 * @member {Boolean} module:link/utils~ManualDecorator#value
@@ -45,14 +45,14 @@ export default class ManualDecorator {
 		this.set( 'value' );
 
 		/**
-		 * The label used in user interface to toggle manual decorator.
+		 * The label used in the user interface to toggle the manual decorator.
 		 *
 		 * @type {String}
 		 */
 		this.label = label;
 
 		/**
-		 * Set of attributes added to downcasted data, when decorator is activated for specific link.
+		 * A set of attributes added to downcasted data when the decorator is activated for a specific link.
 		 * Attributes should be added in a form of attributes defined in {@link module:engine/view/elementdefinition~ElementDefinition}.
 		 *
 		 * @type {Object}