Przeglądaj źródła

Merge branch 'stable'

Piotrek Koszuliński 6 lat temu
rodzic
commit
630c55d225

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

@@ -5,7 +5,7 @@ category: features
 
 
 {@snippet features/build-link-source}
 {@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
 ## Demo
 
 
@@ -27,13 +27,15 @@ CKEditor 5 allows for typing both at inner and outer boundaries of links to make
 
 
 ## Custom link attributes (decorators)
 ## 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>
 <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>
 </info-box>
 
 
 ### Demo
 ### Demo
@@ -57,7 +59,7 @@ ClassicEditor
 			// Automatically add target="_blank" and rel="noopener noreferrer" to all external links.
 			// Automatically add target="_blank" and rel="noopener noreferrer" to all external links.
 			addTargetToExternalLinks: true,
 			addTargetToExternalLinks: true,
 
 
-			// Allow users control the "download" attribute of each link.
+			// Let the users control the "download" attribute of each link.
 			decorators: [
 			decorators: [
 				{
 				{
 					mode: 'manual',
 					mode: 'manual',
@@ -75,15 +77,17 @@ ClassicEditor
 
 
 ### Configuration
 ### 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>
 <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>
 </info-box>
 
 
 #### Adding `target` and `rel` attributes to external links
 #### 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
 ```js
 ClassicEditor
 ClassicEditor
@@ -120,7 +124,7 @@ ClassicEditor
 	.catch( ... );
 	.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
 ```js
 ClassicEditor
 ClassicEditor
@@ -130,7 +134,7 @@ ClassicEditor
 			decorators: {
 			decorators: {
 				addTargetToLinks: {
 				addTargetToLinks: {
 					mode: 'manual',
 					mode: 'manual',
-					label: 'Open link in a new tab',
+					label: 'Open in a new tab',
 					attributes: {
 					attributes: {
 						target: '_blank',
 						target: '_blank',
 						rel: 'noopener noreferrer'
 						rel: 'noopener noreferrer'
@@ -145,7 +149,7 @@ ClassicEditor
 
 
 #### Adding attributes to links based on pre–defined rules (automatic decorators)
 #### 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`}:
 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>
 <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>
 </info-box>
 
 
 #### Adding attributes to links using the UI (manual decorators)
 #### 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`}:
 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' );
 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>
 <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.
 	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.
  * 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}.
  * and {@link module:link/linkui~LinkUI link UI feature}.
  *
  *
  * @extends module:core/plugin~Plugin
  * @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
  *		ClassicEditor
  *			.create( editorElement, {
  *			.create( editorElement, {
@@ -70,15 +70,15 @@ export default class Link extends Plugin {
  *			.then( ... )
  *			.then( ... )
  *			.catch( ... );
  *			.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
  * **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~LinkDecoratorManualDefinition manual} decorator must be defined in the
  * {@link module:link/link~LinkConfig#decorators `config.link.decorators`} array. In such scenario,
  * {@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.
  * 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.
  * 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}
  * 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
  * Decorators provide an easy way to configure and manage additional link attributes in the editor content. There are
  * two types of link decorators:
  * 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.
  *  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.
  * value is the decorator definition.
  *
  *
  * The name of the decorator also corresponds to the {@glink framework/guides/architecture/editing-engine#text-attributes text attribute}
  * 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}
  * 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.
  * 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.
  * 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
  * **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`}
  * {@link module:link/link~LinkConfig#addTargetToExternalLinks `config.link.addTargetToExternalLinks`}
  * configuration description to learn more.
  * 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
  * @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
  * @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.
  * `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',
  *			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
  * **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`}
  * {@link module:link/link~LinkConfig#addTargetToExternalLinks `config.link.addTargetToExternalLinks`}
  * configuration description to learn more.
  * configuration description to learn more.
  *
  *
  * @typedef {Object} module:link/link~LinkDecoratorAutomaticDefinition
  * @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
  * @property {Object} attributes Key-value pairs used as link attributes added to the output during the
  * {@glink framework/guides/architecture/editing-engine#conversion downcasting}.
  * {@glink framework/guides/architecture/editing-engine#conversion downcasting}.
  * Attributes should follow the {@link module:engine/view/elementdefinition~ElementDefinition} syntax.
  * 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:
  * `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
  * @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
  * @property {Object} attributes Key-value pairs used as link attributes added to the output during the
  * {@glink framework/guides/architecture/editing-engine#conversion downcasting}.
  * {@glink framework/guides/architecture/editing-engine#conversion downcasting}.
  * Attributes should follow the {@link module:engine/view/elementdefinition~ElementDefinition} syntax.
  * 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}
 		 * A collection of {@link module:link/utils~ManualDecorator manual decorators}
 		 * corresponding to the {@link module:link/link~LinkConfig#decorators decorator configuration}.
 		 * 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
 		 * @readonly
 		 * @type {module:utils/collection~Collection}
 		 * @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() {
 	restoreManualDecoratorStates() {
 		for ( const manualDecorator of this.manualDecorators ) {
 		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
 	 * 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).
 	 * 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.
 	 * 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.
 	 * 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
 	 * # 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
 	 * {@glink framework/guides/architecture/editing-engine#text-attributes text attributes} brought by
 	 * {@link module:link/utils~ManualDecorator manual link decorators}.
 	 * {@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}.
 	 * 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
 	 * 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`}
 	 * To learn more about link decorators, check out the {@link module:link/link~LinkConfig#decorators `config.link.decorators`}
 	 * documentation.
 	 * 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' );
 	 *		const linkCommand = editor.commands.get( 'link' );
 	 *
 	 *
@@ -101,25 +101,25 @@ export default class LinkCommand extends Command {
 	 *			linkIsExternal: true
 	 *			linkIsExternal: true
 	 *		} );
 	 *		} );
 	 *
 	 *
-	 *		// Removing a decorator attribute from a selection.
+	 *		// Removing a decorator attribute from the selection.
 	 *		linkCommand.execute( 'http://example.com', {
 	 *		linkCommand.execute( 'http://example.com', {
 	 *			linkIsExternal: false
 	 *			linkIsExternal: false
 	 *		} );
 	 *		} );
 	 *
 	 *
-	 *		// Adding multiple decorator attributes at a time.
+	 *		// Adding multiple decorator attributes at the same time.
 	 *		linkCommand.execute( 'http://example.com', {
 	 *		linkCommand.execute( 'http://example.com', {
 	 *			linkIsExternal: true,
 	 *			linkIsExternal: true,
 	 *			linkIsDownloadable: 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', {
 	 *		linkCommand.execute( 'http://example.com', {
 	 *			linkIsExternal: false,
 	 *			linkIsExternal: false,
 	 *			linkFoo: true,
 	 *			linkFoo: true,
 	 *			linkIsDownloadable: false,
 	 *			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
 	 * **Note**: {@link module:link/unlinkcommand~UnlinkCommand#execute `UnlinkCommand#execute()`} removes all
 	 * decorator attributes.
 	 * 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
 	 * @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 ) {
 	_getDecoratorStateFromModel( decoratorName ) {
 		const doc = this.editor.model.document;
 		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
 	 * for each one of them. Downcast dispatchers are obtained using the
 	 * {@link module:link/utils~AutomaticDecorators#getDispatcher} method.
 	 * {@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`}.
 	 * {@link module:link/link~LinkConfig#addTargetToExternalLinks `config.link.addTargetToExternalLinks`}.
 	 *
 	 *
 	 * @private
 	 * @private
@@ -112,7 +112,7 @@ export default class LinkEditing extends Plugin {
 		const editor = this.editor;
 		const editor = this.editor;
 		const automaticDecorators = new AutomaticDecorators();
 		const automaticDecorators = new AutomaticDecorators();
 
 
-		// Adds default decorator for external links.
+		// Adds a default decorator for external links.
 		if ( editor.config.get( 'link.addTargetToExternalLinks' ) ) {
 		if ( editor.config.get( 'link.addTargetToExternalLinks' ) ) {
 			automaticDecorators.add( {
 			automaticDecorators.add( {
 				id: 'linkIsExternal',
 				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).
 	 * {@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}
 	 * converter for each manual decorator and extends the {@link module:engine/model/schema~Schema model's schema}
 	 * with adequate model attributes.
 	 * 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.
 	 * 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.
 	 * 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
 	 * @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.
 	 * Creates the {@link module:link/ui/linkformview~LinkFormView} instance.
 	 *
 	 *
 	 * @private
 	 * @private
-	 * @returns {module:link/ui/linkformview~LinkFormView} The link form instance.
+	 * @returns {module:link/ui/linkformview~LinkFormView} The link form view instance.
 	 */
 	 */
 	_createFormView() {
 	_createFormView() {
 		const editor = this.editor;
 		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
 	 * @private
 	 */
 	 */
 	_closeFormView() {
 	_closeFormView() {
 		const linkCommand = this.editor.commands.get( 'link' );
 		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();
 		linkCommand.restoreManualDecoratorStates();
 
 
 		if ( linkCommand.value !== undefined ) {
 		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}.
 	 * {@link #formView} or {@link #actionsView}.
 	 *
 	 *
 	 * @param {Boolean} forceVisible
 	 * @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
 	 * 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.
 	 * 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
 	 * @readonly
 	 * @protected
 	 * @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
 	 * @readonly
 	 * @protected
 	 * @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.
 	 * currently visible.
 	 *
 	 *
 	 * @readonly
 	 * @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
 	 * @readonly
 	 * @protected
 	 * @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.
 	 * currently visible.
 	 *
 	 *
 	 * @readonly
 	 * @readonly
@@ -575,7 +575,7 @@ export default class LinkUI extends Plugin {
 	 * the {@link module:engine/view/document~Document editing view's} selection or `null`
 	 * the {@link module:engine/view/document~Document editing view's} selection or `null`
 	 * if there is none.
 	 * 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.
 	 * selected and the **only** element within the selection boundaries.
 	 *
 	 *
 	 * @private
 	 * @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';
 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.
  * unlinking or editing the link.
  *
  *
  * @extends module:ui/view~View
  * @extends module:ui/view~View
@@ -75,7 +75,7 @@ export default class LinkActionsView extends View {
 		this.editButtonView = this._createButton( t( 'Edit link' ), pencilIcon, 'edit' );
 		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
 		 * @observable
 		 * @member {String}
 		 * @member {String}
@@ -83,7 +83,7 @@ export default class LinkActionsView extends View {
 		this.set( 'href' );
 		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
 		 * @readonly
 		 * @protected
 		 * @protected
@@ -168,7 +168,7 @@ export default class LinkActionsView extends View {
 	 *
 	 *
 	 * @private
 	 * @private
 	 * @param {String} label The button label.
 	 * @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.
 	 * @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.
 	 * @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 );
 		this._manualDecoratorSwitches = this._createManualDecoratorSwitches( manualDecorators );
 
 
 		/**
 		/**
-		 * Collection of child views in the form.
+		 * A collection of child views in the form.
 		 *
 		 *
 		 * @readonly
 		 * @readonly
 		 * @type {module:ui/viewcollection~ViewCollection}
 		 * @type {module:ui/viewcollection~ViewCollection}
@@ -104,7 +104,7 @@ export default class LinkFormView extends View {
 		this.children = this._createFormChildren( manualDecorators );
 		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
 		 * @readonly
 		 * @protected
 		 * @protected
@@ -157,7 +157,7 @@ export default class LinkFormView extends View {
 	 * {@link module:link/linkcommand~LinkCommand#manualDecorators manual link decorators}
 	 * {@link module:link/linkcommand~LinkCommand#manualDecorators manual link decorators}
 	 * in the {@link module:link/ui/linkformview~LinkFormView}.
 	 * 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.
 	 * its state.
 	 */
 	 */
 	getDecoratorSwitchesState() {
 	getDecoratorSwitchesState() {
@@ -225,7 +225,7 @@ export default class LinkFormView extends View {
 	 *
 	 *
 	 * @private
 	 * @private
 	 * @param {String} label The button label.
 	 * @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} className The additional button CSS class name.
 	 * @param {String} [eventName] An event name that the `ButtonView#execute` event will be delegated to.
 	 * @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.
 	 * @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}
 	 * 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
 	 * @private
 	 * @param {module:utils/collection~Collection} manualDecorators A reference to the
 	 * @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 ) {
 	_createManualDecoratorSwitches( manualDecorators ) {
 		const switches = this.createCollection();
 		const switches = this.createCollection();
@@ -288,14 +288,14 @@ export default class LinkFormView extends View {
 	/**
 	/**
 	 * Populates the {@link #children} collection of the form.
 	 * 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
 	 * additional `View` wrapping all {@link #_manualDecoratorSwitches} switch buttons corresponding
-	 * to those decorators.
+	 * to these decorators.
 	 *
 	 *
 	 * @private
 	 * @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 ) {
 	_createFormChildren( manualDecorators ) {
 		const children = this.createCollection();
 		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),
  * 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
  * @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
  * @event cancel
  */
  */

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

@@ -26,8 +26,8 @@ export default class UnlinkCommand extends Command {
 	/**
 	/**
 	 * Executes the 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
 	 * # 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
  * @param {String} href
  * @returns {module:engine/view/attributeelement~AttributeElement}
  * @returns {module:engine/view/attributeelement~AttributeElement}
@@ -39,9 +39,9 @@ export function createLinkElement( href, writer ) {
 /**
 /**
  * Returns a safe URL based on a given value.
  * 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
  * @protected
  * @param {*} url
  * @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.
  * in the correct language.
  *
  *
  * **Note**: Only the few most commonly used labels are translated automatically. Other labels should be manually
  * **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.
  * 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 {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>}
  * @returns {Array.<module:link/link~LinkDecoratorDefinition>}
  */
  */
 export function getLocalizedDecorators( t, decorators ) {
 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
  * @param {Object.<String, module:link/link~LinkDecoratorDefinition>} decorators
  * @returns {Array.<module:link/link~LinkDecoratorDefinition>}
  * @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.
  * a {@link module:engine/conversion/downcasthelpers~DowncastHelpers#attributeToElement downcast dispatcher} for them.
  */
  */
 export default class AutomaticDecorators {
 export default class AutomaticDecorators {
 	constructor() {
 	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
 		 * @private
 		 * @type {Set}
 		 * @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
 	 * @readonly
 	 * @protected
 	 * @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
 	 * @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 ) {
 	add( item ) {
 		if ( Array.isArray( 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() {
 	getDispatcher() {
 		return dispatcher => {
 		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';
 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}.
  * These decorators are kept as collections in {@link module:link/linkcommand~LinkCommand#manualDecorators}.
  *
  *
  * @mixes module:utils/observablemixin~ObservableMixin
  * @mixes module:utils/observablemixin~ObservableMixin
  */
  */
 export default class ManualDecorator {
 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 {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 } ) {
 	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}
 		 * @type {String}
 		 */
 		 */
 		this.id = id;
 		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
 		 * @observable
 		 * @member {Boolean} module:link/utils~ManualDecorator#value
 		 * @member {Boolean} module:link/utils~ManualDecorator#value
@@ -45,14 +45,14 @@ export default class ManualDecorator {
 		this.set( 'value' );
 		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}
 		 * @type {String}
 		 */
 		 */
 		this.label = label;
 		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}.
 		 * Attributes should be added in a form of attributes defined in {@link module:engine/view/elementdefinition~ElementDefinition}.
 		 *
 		 *
 		 * @type {Object}
 		 * @type {Object}