8
0
فهرست منبع

Docs: API docs and guides of the mention feature corrected. [skip ci]

Anna Tomanek 6 سال پیش
والد
کامیت
d78042ac88

+ 5 - 1
packages/ckeditor5-mention/README.md

@@ -10,7 +10,11 @@ CKEditor 5 mention feature
 [![Dependency Status](https://david-dm.org/ckeditor/ckeditor5-mention/status.svg)](https://david-dm.org/ckeditor/ckeditor5-mention)
 [![Dependency Status](https://david-dm.org/ckeditor/ckeditor5-mention/status.svg)](https://david-dm.org/ckeditor/ckeditor5-mention)
 [![devDependency Status](https://david-dm.org/ckeditor/ckeditor5-mention/dev-status.svg)](https://david-dm.org/ckeditor/ckeditor5-mention?type=dev)
 [![devDependency Status](https://david-dm.org/ckeditor/ckeditor5-mention/dev-status.svg)](https://david-dm.org/ckeditor/ckeditor5-mention?type=dev)
 
 
-This package implements mention support for CKEditor 5.
+This package implements mention support for CKEditor 5 and brings smart autocompletion based on user input.
+
+## Demo
+
+Check out the demo in the [Mentions (autocomplete) feature](https://ckeditor.com/docs/ckeditor5/latest/features/mentions.html) guide.
 
 
 ## Documentation
 ## Documentation
 
 

+ 3 - 3
packages/ckeditor5-mention/docs/_snippets/features/custom-mention-colors-variables.html

@@ -1,10 +1,10 @@
 <style>
 <style>
-	/* We are not using here :root because of many instances of editor */
+	/* We are not using :root here because of many instances of the editor. */
 	#snippet-mention-custom-colors + .ck-editor {
 	#snippet-mention-custom-colors + .ck-editor {
-		/* Make mention background blue. */
+		/* Make the mention background blue. */
 		--ck-color-mention-background: hsla(220, 100%, 54%, 0.4);
 		--ck-color-mention-background: hsla(220, 100%, 54%, 0.4);
 
 
-		/* Make mention text dark grey. */
+		/* Make the mention text dark grey. */
 		--ck-color-mention-text: hsl(0, 0%, 15%);
 		--ck-color-mention-text: hsl(0, 0%, 15%);
 	}
 	}
 </style>
 </style>

+ 6 - 6
packages/ckeditor5-mention/docs/_snippets/features/mention-customization.js

@@ -52,7 +52,7 @@ function MentionCustomization( editor ) {
 			value: viewItem => {
 			value: viewItem => {
 				// The mention feature expects that the mention attribute value
 				// The mention feature expects that the mention attribute value
 				// in the model is a plain object with a set of additional attributes.
 				// in the model is a plain object with a set of additional attributes.
-				// In order to create a proper object use the toMentionAttribute() helper method:
+				// In order to create a proper object, use the toMentionAttribute() helper method:
 				const mentionAttribute = editor.plugins.get( 'Mention' ).toMentionAttribute( viewItem, {
 				const mentionAttribute = editor.plugins.get( 'Mention' ).toMentionAttribute( viewItem, {
 					// Add any other properties that you need.
 					// Add any other properties that you need.
 					link: viewItem.getAttribute( 'href' ),
 					link: viewItem.getAttribute( 'href' ),
@@ -94,13 +94,13 @@ const items = [
 ];
 ];
 
 
 function getFeedItems( queryText ) {
 function getFeedItems( queryText ) {
-	// As an example of an asynchronous action, let's return a promise
+	// As an example of an asynchronous action, return a promise
 	// that resolves after a 100ms timeout.
 	// that resolves after a 100ms timeout.
 	// This can be a server request or any sort of delayed action.
 	// This can be a server request or any sort of delayed action.
 	return new Promise( resolve => {
 	return new Promise( resolve => {
 		setTimeout( () => {
 		setTimeout( () => {
 			const itemsToDisplay = items
 			const itemsToDisplay = items
-				// Filter out the full list of all items to only those matching queryText.
+				// Filter out the full list of all items to only those matching the query text.
 				.filter( isItemMatching )
 				.filter( isItemMatching )
 				// Return 10 items max - needed for generic queries when the list may contain hundreds of elements.
 				// Return 10 items max - needed for generic queries when the list may contain hundreds of elements.
 				.slice( 0, 10 );
 				.slice( 0, 10 );
@@ -109,12 +109,12 @@ function getFeedItems( queryText ) {
 		}, 100 );
 		}, 100 );
 	} );
 	} );
 
 
-	// Filtering function - it uses `name` and `username` properties of an item to find a match.
+	// Filtering function - it uses the `name` and `username` properties of an item to find a match.
 	function isItemMatching( item ) {
 	function isItemMatching( item ) {
-		// Make search case-insensitive.
+		// Make the search case-insensitive.
 		const searchString = queryText.toLowerCase();
 		const searchString = queryText.toLowerCase();
 
 
-		// Include an item in the search results if name or username includes the current user input.
+		// Include an item in the search results if the name or username includes the current user input.
 		return (
 		return (
 			item.name.toLowerCase().includes( searchString ) ||
 			item.name.toLowerCase().includes( searchString ) ||
 			item.id.toLowerCase().includes( searchString )
 			item.id.toLowerCase().includes( searchString )

+ 1 - 1
packages/ckeditor5-mention/docs/api/mention.md

@@ -6,7 +6,7 @@ category: api-reference
 
 
 [![npm version](https://badge.fury.io/js/%40ckeditor%2Fckeditor5-mention.svg)](https://www.npmjs.com/package/@ckeditor/ckeditor5-mention)
 [![npm version](https://badge.fury.io/js/%40ckeditor%2Fckeditor5-mention.svg)](https://www.npmjs.com/package/@ckeditor/ckeditor5-mention)
 
 
-This package implements the mention feature for CKEditor 5. This features provides smart completion functionality for custom text matches based on user input.
+This package implements the mention feature for CKEditor 5. It provides smart completion functionality for custom text matches based on user input.
 
 
 ## Demo
 ## Demo
 
 

+ 29 - 29
packages/ckeditor5-mention/docs/features/mentions.md

@@ -11,7 +11,7 @@ The {@link module:mention/mention~Mention} feature brings support for smart auto
 
 
 ## Demo
 ## Demo
 
 
-You can type the "@" character to invoke mention autocomplete UI. The demo below is configured to suggest a static list of names ("Barney", "Lily", "Marshall", "Robin", and "Ted").
+You can type the "@" character to invoke the mention autocomplete UI. The demo below is configured to suggest a static list of names ("Barney", "Lily", "Marshall", "Robin", and "Ted").
 
 
 {@snippet features/mention}
 {@snippet features/mention}
 
 
@@ -46,24 +46,24 @@ Additionally, you can configure:
 
 
 * How the item is rendered in the autocomplete panel (via setting {@link module:mention/mention~MentionFeed `itemRenderer`}). See ["Customizing the autocomplete list"](#customizing-the-autocomplete-list).
 * How the item is rendered in the autocomplete panel (via setting {@link module:mention/mention~MentionFeed `itemRenderer`}). See ["Customizing the autocomplete list"](#customizing-the-autocomplete-list).
 * How the item is converted during the {@link framework/guides/architecture/editing-engine#conversion conversion}. See ["Customizing the output"](#customizing-the-output).
 * How the item is converted during the {@link framework/guides/architecture/editing-engine#conversion conversion}. See ["Customizing the output"](#customizing-the-output).
-* Multiple feeds &mdash; in the demo above we used only one feed, which is triggered by the `'@'` character. You can define multiple feeds but they must use different markers. For example, you can use `'@'` for people and `'#'` for tags.
+* Multiple feeds. Te demo above uses only one feed, which is triggered by the `'@'` character. You can define multiple feeds but they must use different markers. For example, you can use `'@'` for people and `'#'` for tags.
 
 
 ### Providing the feed
 ### Providing the feed
 
 
 The {@link module:mention/mention~MentionFeed `feed`} can be provided as:
 The {@link module:mention/mention~MentionFeed `feed`} can be provided as:
 
 
-* a static array &mdash; good for scenarios with a relatively small set of autocomplete items.
-* a callback &mdash; which provides more control over the returned list of items.
+* A static array &ndash; Good for scenarios with a relatively small set of autocomplete items.
+* A callback &ndash; It provides more control over the returned list of items.
 
 
-When using a callback you can return a `Promise` that resolves with the list of {@link module:mention/mention~MentionFeedItem matching feed items}. Those can be simple strings or plain objects with at least the `name` property. The other properties of this object can later be used e.g. when [customizing the autocomplete list](#customizing-the-autocomplete-list) or [customizing the output](#customizing-the-output).
+When using a callback you can return a `Promise` that resolves with the list of {@link module:mention/mention~MentionFeedItem matching feed items}. These can be simple strings or plain objects with at least the `name` property. The other properties of this object can later be used e.g. when [customizing the autocomplete list](#customizing-the-autocomplete-list) or [customizing the output](#customizing-the-output).
 
 
 <info-box>
 <info-box>
 	When using external resources to obtain the feed it is recommended to add some caching mechanism so subsequent calls for the same suggestion would load faster.
 	When using external resources to obtain the feed it is recommended to add some caching mechanism so subsequent calls for the same suggestion would load faster.
 
 
-	You can also consider adding the `minimumCharacters` option to the feed config so the editor will call the feed callback after minimum characters typed instead of action on marker alone.
+	You can also consider adding the `minimumCharacters` option to the feed configuration so the editor will call the feed callback after some minimum number of characters typed instead of an action on a marker alone.
 </info-box>
 </info-box>
 
 
-The callback receives the query text which should be used to filter item suggestions. It should return a `Promise` and resolve it with an array of items that match to the feed text.
+The callback receives the query text which should be used to filter item suggestions. It should return a `Promise` and resolve it with an array of items that match the feed text.
 
 
 ```js
 ```js
 ClassicEditor
 ClassicEditor
@@ -79,7 +79,7 @@ ClassicEditor
 					feed: getFeedItems
 					feed: getFeedItems
 				}
 				}
 			}
 			}
-		}
+		]
 	} )
 	} )
 	.then( ... )
 	.then( ... )
 	.catch( ... );
 	.catch( ... );
@@ -93,13 +93,13 @@ const items = [
 ];
 ];
 
 
 function getFeedItems( queryText ) {
 function getFeedItems( queryText ) {
-	// As an example of an asynchronous action, let's return a promise
+	// As an example of an asynchronous action, return a promise
 	// that resolves after a 100ms timeout.
 	// that resolves after a 100ms timeout.
 	// This can be a server request or any sort of delayed action.
 	// This can be a server request or any sort of delayed action.
 	return new Promise( resolve => {
 	return new Promise( resolve => {
 		setTimeout( () => {
 		setTimeout( () => {
 			const itemsToDisplay = items
 			const itemsToDisplay = items
-				// Filter out the full list of all items to only those matching queryText.
+				// Filter out the full list of all items to only those matching the query text.
 				.filter( isItemMatching )
 				.filter( isItemMatching )
 				// Return 10 items max - needed for generic queries when the list may contain hundreds of elements.
 				// Return 10 items max - needed for generic queries when the list may contain hundreds of elements.
 				.slice( 0, 10 );
 				.slice( 0, 10 );
@@ -108,12 +108,12 @@ function getFeedItems( queryText ) {
 		}, 100 );
 		}, 100 );
 	} );
 	} );
 
 
-	// Filtering function - it uses `name` and `username` properties of an item to find a match.
+	// Filtering function - it uses the `name` and `username` properties of an item to find a match.
 	function isItemMatching( item ) {
 	function isItemMatching( item ) {
-		// Make search case-insensitive.
+		// Make the search case-insensitive.
 		const searchString = queryText.toLowerCase();
 		const searchString = queryText.toLowerCase();
 
 
-		// Include an item in the search results if name or username includes the current user input.
+		// Include an item in the search results if the name or username includes the current user input.
 		return (
 		return (
 			item.name.toLowerCase().includes( searchString ) ||
 			item.name.toLowerCase().includes( searchString ) ||
 			item.id.toLowerCase().includes( searchString )
 			item.id.toLowerCase().includes( searchString )
@@ -138,7 +138,7 @@ ClassicEditor
 			feeds: [
 			feeds: [
 				{
 				{
 					feed: [ ... ],
 					feed: [ ... ],
-					// Define the custom item renderer:
+					// Define the custom item renderer.
 					itemRenderer: customItemRenderer
 					itemRenderer: customItemRenderer
 				}
 				}
 			]
 			]
@@ -171,7 +171,7 @@ A full, working demo with all possible customizations and its source code is ava
 
 
 In order to change the markup generated by the editor for mentions, you can overwrite the default converter of the mention feature. To do that, you must specify both {@link module:engine/conversion/upcastdispatcher~UpcastDispatcher upcast} and {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher downcast} converters.
 In order to change the markup generated by the editor for mentions, you can overwrite the default converter of the mention feature. To do that, you must specify both {@link module:engine/conversion/upcastdispatcher~UpcastDispatcher upcast} and {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher downcast} converters.
 
 
-The example below defined a plugin which overrides the default output:
+The example below defines a plugin that overrides the default output:
 
 
 ```html
 ```html
 <span data-mention="@Ted" class="mention">@Ted</span>
 <span data-mention="@Ted" class="mention">@Ted</span>
@@ -183,12 +183,12 @@ To a link:
 <a class="mention" data-mention="@Ted" data-user-id="5" href="https://www.imdb.com/title/tt0460649/characters/nm1102140">@tdog</a>
 <a class="mention" data-mention="@Ted" data-user-id="5" href="https://www.imdb.com/title/tt0460649/characters/nm1102140">@tdog</a>
 ```
 ```
 
 
-The converters must be defined with a `'high'` priority to be executed before the {@link features/link link} feature's converter and before the default converter of the mention feature. A mention is stored in the model as a {@link framework/guides/architecture/editing-engine#text-attributes text attribute} which stores an object (see {@link module:mention/mention~MentionFeedItem}).
+The converters must be defined with a `'high'` priority to be executed before the {@link features/link link} feature's converter and before the default converter of the mention feature. A mention is stored in the model as a {@link framework/guides/architecture/editing-engine#text-attributes text attribute} that stores an object (see {@link module:mention/mention~MentionFeedItem}).
 
 
 ```js
 ```js
 ClassicEditor
 ClassicEditor
 	.create( document.querySelector( '#editor' ), {
 	.create( document.querySelector( '#editor' ), {
-		plugins: [ Mention, MentionCustomization, ... ], // Add custom mention plugin function.
+		plugins: [ Mention, MentionCustomization, ... ], // Add the custom mention plugin function.
 		mention: {
 		mention: {
 			// Configuration...
 			// Configuration...
 		}
 		}
@@ -248,7 +248,7 @@ function MentionCustomization( editor ) {
 }
 }
 ```
 ```
 
 
-The full working demo with all customization possible is {@link features/mentions#fully-customized-mention-feed  at the end of this section}.
+A full, working demo with all possible customizations and its source code is available {@link features/mentions#fully-customized-mention-feed at the end of this section}.
 
 
 ### Fully customized mention feed
 ### Fully customized mention feed
 
 
@@ -256,7 +256,7 @@ Below is an example of a customized mention feature that:
 
 
 * Uses a feed of items with additional properties (`id`, `username`, `link`).
 * Uses a feed of items with additional properties (`id`, `username`, `link`).
 * Renders custom item views in the autocomplete panel.
 * Renders custom item views in the autocomplete panel.
-* Converts mention to an `<a>` element instead of a `<span>`.
+* Converts a mention to an `<a>` element instead of a `<span>`.
 
 
 {@snippet features/mention-customization}
 {@snippet features/mention-customization}
 
 
@@ -300,8 +300,8 @@ function MentionCustomization( editor ) {
 			key: 'mention',
 			key: 'mention',
 			value: viewItem => {
 			value: viewItem => {
 				// The mention feature expects that the mention attribute value
 				// The mention feature expects that the mention attribute value
-				// in the model is a plain object with set of additional attributes.
-				// In order to create proper object use `toMentionAttribute` helper method:
+				// in the model is a plain object with a set of additional attributes.
+				// In order to create a proper object, use the toMentionAttribute helper method:
 				const mentionAttribute = editor.plugins.get( 'Mention' ).toMentionAttribute( viewItem, {
 				const mentionAttribute = editor.plugins.get( 'Mention' ).toMentionAttribute( viewItem, {
 					// Add any other properties that you need.
 					// Add any other properties that you need.
 					link: viewItem.getAttribute( 'href' ),
 					link: viewItem.getAttribute( 'href' ),
@@ -314,7 +314,7 @@ function MentionCustomization( editor ) {
 		converterPriority: 'high'
 		converterPriority: 'high'
 	} );
 	} );
 
 
-	// Do not forget to define a downcast converter as well:
+	// Downcast the model 'mention' text attribute to a view <a> element.
 	editor.conversion.for( 'downcast' ).attributeToElement( {
 	editor.conversion.for( 'downcast' ).attributeToElement( {
 		model: 'mention',
 		model: 'mention',
 		view: ( modelAttributeValue, viewWriter ) => {
 		view: ( modelAttributeValue, viewWriter ) => {
@@ -343,13 +343,13 @@ const items = [
 ];
 ];
 
 
 function getFeedItems( queryText ) {
 function getFeedItems( queryText ) {
-	// As an example of an asynchronous action, let's return a promise
+	// As an example of an asynchronous action, return a promise
 	// that resolves after a 100ms timeout.
 	// that resolves after a 100ms timeout.
 	// This can be a server request or any sort of delayed action.
 	// This can be a server request or any sort of delayed action.
 	return new Promise( resolve => {
 	return new Promise( resolve => {
 		setTimeout( () => {
 		setTimeout( () => {
 			const itemsToDisplay = items
 			const itemsToDisplay = items
-				// Filter out the full list of all items to only those matching queryText.
+				// Filter out the full list of all items to only those matching the query text.
 				.filter( isItemMatching )
 				.filter( isItemMatching )
 				// Return 10 items max - needed for generic queries when the list may contain hundreds of elements.
 				// Return 10 items max - needed for generic queries when the list may contain hundreds of elements.
 				.slice( 0, 10 );
 				.slice( 0, 10 );
@@ -360,7 +360,7 @@ function getFeedItems( queryText ) {
 
 
 	// Filtering function - it uses `name` and `username` properties of an item to find a match.
 	// Filtering function - it uses `name` and `username` properties of an item to find a match.
 	function isItemMatching( item ) {
 	function isItemMatching( item ) {
-		// Make search case-insensitive.
+		// Make the search case-insensitive.
 		const searchString = queryText.toLowerCase();
 		const searchString = queryText.toLowerCase();
 
 
 		// Include an item in the search results if name or username includes the current user input.
 		// Include an item in the search results if name or username includes the current user input.
@@ -393,14 +393,14 @@ function customItemRenderer( item ) {
 
 
 #### Using CSS variables
 #### Using CSS variables
 
 
-The mention feature is using the power of [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_variables) which are defined in the [theme lark stylesheet](https://github.com/ckeditor/ckeditor5-theme-lark/blob/master/theme/ckeditor5-mention/mentionediting.css). Thanks to that mention styles can be {@link framework/guides/theme-customization easily customized}:
+The mention feature is using the power of [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_variables) which are defined in the [Lark theme stylesheet](https://github.com/ckeditor/ckeditor5-theme-lark/blob/master/theme/ckeditor5-mention/mentionediting.css). Thanks to that, mention styles can be {@link framework/guides/theme-customization easily customized}:
 
 
 ```css
 ```css
 :root {
 :root {
-	/* Make mention background blue. */
+	/* Make the mention background blue. */
 	--ck-color-mention-background: hsla(220, 100%, 54%, 0.4);
 	--ck-color-mention-background: hsla(220, 100%, 54%, 0.4);
 
 
-	/* Make mention text dark grey. */
+	/* Make the mention text dark grey. */
 	--ck-color-mention-text: hsl(0, 0%, 15%);
 	--ck-color-mention-text: hsl(0, 0%, 15%);
 }
 }
 ```
 ```
@@ -438,7 +438,7 @@ ClassicEditor
 ## Common API
 ## Common API
 
 
 The {@link module:mention/mention~Mention} plugin registers:
 The {@link module:mention/mention~Mention} plugin registers:
-* the `'mention'` command implemented by {@link module:mention/mentioncommand~MentionCommand}.
+* The `'mention'` command implemented by {@link module:mention/mentioncommand~MentionCommand}.
 
 
 	You can insert a mention element by executing the following code:
 	You can insert a mention element by executing the following code:
 
 

+ 13 - 12
packages/ckeditor5-mention/src/mention.js

@@ -27,7 +27,7 @@ export default class Mention extends Plugin {
 	 *
 	 *
 	 *		editor.plugins.get( 'Mention' ).toMentionAttribute( viewElement, { userId: '1234' } );
 	 *		editor.plugins.get( 'Mention' ).toMentionAttribute( viewElement, { userId: '1234' } );
 	 *
 	 *
-	 *		// for a viewElement: <span data-mention="@joe">@John Doe</span>
+	 *		// For a view element: <span data-mention="@joe">@John Doe</span>
 	 *		// it will return:
 	 *		// it will return:
 	 *		// { id: '@joe', userId: '1234', _uid: '7a7bc7...', _text: '@John Doe' }
 	 *		// { id: '@joe', userId: '1234', _uid: '7a7bc7...', _text: '@John Doe' }
 	 *
 	 *
@@ -70,7 +70,7 @@ export default class Mention extends Plugin {
  *
  *
  *		ClassicEditor
  *		ClassicEditor
  *			.create( editorElement, {
  *			.create( editorElement, {
- *				mention: ... // Media embed feature options.
+ *				mention: ... // Mention feature options.
  *			} )
  *			} )
  *			.then( ... )
  *			.then( ... )
  *			.catch( ... );
  *			.catch( ... );
@@ -99,7 +99,7 @@ export default class Mention extends Plugin {
  *			.then( ... )
  *			.then( ... )
  *			.catch( ... );
  *			.catch( ... );
  *
  *
- * You can provide as many mention feeds but they must use different `marker`s.
+ * You can provide many mention feeds but they must use different `marker`s.
  * For example, you can use `'@'` to autocomplete people and `'#'` to autocomplete tags.
  * For example, you can use `'@'` to autocomplete people and `'#'` to autocomplete tags.
  *
  *
  * @member {Array.<module:mention/mention~MentionFeed>} module:mention/mention~MentionConfig#feeds
  * @member {Array.<module:mention/mention~MentionFeed>} module:mention/mention~MentionConfig#feeds
@@ -117,7 +117,7 @@ export default class Mention extends Plugin {
  *			minimumCharacters: 2
  *			minimumCharacters: 2
  *		};
  *		};
  *
  *
- *		// Simple, synchronous callback.
+ *		// Simple synchronous callback.
  *		const mentionFeedTags = {
  *		const mentionFeedTags = {
  *			marker: '#',
  *			marker: '#',
  *			feed: searchString => {
  *			feed: searchString => {
@@ -154,18 +154,18 @@ export default class Mention extends Plugin {
  *
  *
  * @typedef {Object} module:mention/mention~MentionFeed
  * @typedef {Object} module:mention/mention~MentionFeed
  * @property {String} [marker] The character which triggers autocompletion for mention. It must be a single character.
  * @property {String} [marker] The character which triggers autocompletion for mention. It must be a single character.
- * @property {Array.<module:mention/mention~MentionFeedItem>|Function} feed The autocomplete items. Provide an array for
+ * @property {Array.<module:mention/mention~MentionFeedItem>|Function} feed Autocomplete items. Provide an array for
  * a static configuration (the mention feature will show matching items automatically) or a function which returns an array of
  * a static configuration (the mention feature will show matching items automatically) or a function which returns an array of
  * matching items (directly, or via a promise).
  * matching items (directly, or via a promise).
  * @property {Number} [minimumCharacters=0] Specifies after how many characters the autocomplete panel should be shown.
  * @property {Number} [minimumCharacters=0] Specifies after how many characters the autocomplete panel should be shown.
- * @property {Function} [itemRenderer] Function that renders a {@link module:mention/mention~MentionFeedItem}
+ * @property {Function} [itemRenderer] A function that renders a {@link module:mention/mention~MentionFeedItem}
  * to the autocomplete panel.
  * to the autocomplete panel.
  */
  */
 
 
 /**
 /**
  * The mention feed item. It may be defined as a string or a plain object.
  * The mention feed item. It may be defined as a string or a plain object.
  *
  *
- * When defining a feed item as a plain object, the `id` property is obligatory. The additional properties
+ * When defining a feed item as a plain object, the `id` property is obligatory. Additional properties
  * can be used when customizing the mention feature bahavior
  * can be used when customizing the mention feature bahavior
  * (see {@glink features/mentions#customizing-the-autocomplete-list "Customizing the autocomplete list"}
  * (see {@glink features/mentions#customizing-the-autocomplete-list "Customizing the autocomplete list"}
  * and {@glink features/mentions#customizing-the-output "Customizing the output"} sections).
  * and {@glink features/mentions#customizing-the-output "Customizing the output"} sections).
@@ -215,18 +215,19 @@ export default class Mention extends Plugin {
  *			.catch( ... );
  *			.catch( ... );
  *
  *
  * @typedef {Object|String} module:mention/mention~MentionFeedItem
  * @typedef {Object|String} module:mention/mention~MentionFeedItem
- * @property {String} id Unique id of the mention. It must start with the marker character.
+ * @property {String} id A unique ID of the mention. It must start with the marker character.
  * @property {String} [text] Text inserted into the editor when creating a mention.
  * @property {String} [text] Text inserted into the editor when creating a mention.
  */
  */
 
 
 /**
 /**
- * Represents mention in the model.
+ * Represents a mention in the model.
  *
  *
  * See {@link module:mention/mention~Mention#toMentionAttribute `Mention#toMentionAttribute()`}.
  * See {@link module:mention/mention~Mention#toMentionAttribute `Mention#toMentionAttribute()`}.
  *
  *
  * @interface module:mention/mention~MentionAttribute
  * @interface module:mention/mention~MentionAttribute
- * @property {String} id Id of a mention – identifies the mention item in mention feed.
- * @property {String} _uid Internal mention view item id. Should be passed as an `option.id` when using
+ * @property {String} id The ID of a mention. It identifies the mention item in the mention feed.
+ * @property {String} _uid An internal mention view item ID. Should be passed as an `option.id` when using
  * {@link module:engine/view/downcastwriter~DowncastWriter#createAttributeElement writer.createAttributeElement()}.
  * {@link module:engine/view/downcastwriter~DowncastWriter#createAttributeElement writer.createAttributeElement()}.
- * @property {String} _text Helper property that holds text of inserted mention. Used for detecting broken mention in the editing area.
+ * @property {String} _text Helper property that stores the text of the inserted mention. Used for detecting a broken mention
+ * in the editing area.
  */
  */

+ 15 - 14
packages/ckeditor5-mention/src/mentioncommand.js

@@ -15,14 +15,14 @@ import { _addMentionAttributes } from './mentionediting';
 /**
 /**
  * The mention command.
  * The mention command.
  *
  *
- * The command is registered by the {@link module:mention/mentionediting~MentionEditing} as `'mention'`.
+ * The command is registered by {@link module:mention/mentionediting~MentionEditing} as `'mention'`.
  *
  *
- * To insert a mention on a range, execute the command and specify a mention object and a range to replace:
+ * To insert a mention onto a range, execute the command and specify a mention object with a range to replace:
  *
  *
  *		const focus = editor.model.document.selection.focus;
  *		const focus = editor.model.document.selection.focus;
  *
  *
- *		// It will replace one character before selection focus with '#1234' text
- *		// with mention attribute filled with passed attributes.
+ *		// It will replace one character before the selection focus with the '#1234' text
+ *		// with the mention attribute filled with passed attributes.
  *		editor.execute( 'mention', {
  *		editor.execute( 'mention', {
  *			marker: '#',
  *			marker: '#',
  *			mention: {
  *			mention: {
@@ -33,8 +33,8 @@ import { _addMentionAttributes } from './mentionediting';
  *			range: model.createRange( focus, focus.getShiftedBy( -1 ) )
  *			range: model.createRange( focus, focus.getShiftedBy( -1 ) )
  *		} );
  *		} );
  *
  *
- *		// It will replace one character before selection focus with 'Teh "Big Foo"' text
- *		// with attribute filled with passed attributes.
+ *		// It will replace one character before the selection focus with the 'The "Big Foo"' text
+ *		// with the mention attribute filled with passed attributes.
  *		editor.execute( 'mention', {
  *		editor.execute( 'mention', {
  *			marker: '#',
  *			marker: '#',
  *			mention: {
  *			mention: {
@@ -63,12 +63,13 @@ export default class MentionCommand extends Command {
 	 * Executes the command.
 	 * Executes the command.
 	 *
 	 *
 	 * @param {Object} [options] Options for the executed command.
 	 * @param {Object} [options] Options for the executed command.
-	 * @param {Object|String} options.mention Mention object to insert. If passed a string it will be used to create a plain object with
-	 * name attribute equal to passed string.
+	 * @param {Object|String} options.mention The mention object to insert. When a string is passed, it will be used to create a plain
+	 * object with the name attribute that equals the passed string.
 	 * @param {String} options.marker The marker character (e.g. `'@'`).
 	 * @param {String} options.marker The marker character (e.g. `'@'`).
-	 * @param {String} [options.text] The text of inserted mention. Defaults to full mention string composed from `marker` and
-	 * `mention` string or `mention.id` if object is passed.
-	 * @param {String} [options.range] Range to replace. Note that replace range might be shorter then inserted text with mention attribute.
+	 * @param {String} [options.text] The text of the inserted mention. Defaults to the full mention string composed from `marker` and
+	 * `mention` string or `mention.id` if an object is passed.
+	 * @param {String} [options.range] The range to replace. Note that the replaced range might be shorter than the inserted text with the
+	 * mention attribute.
 	 * @fires execute
 	 * @fires execute
 	 */
 	 */
 	execute( options ) {
 	execute( options ) {
@@ -102,7 +103,7 @@ export default class MentionCommand extends Command {
 
 
 		if ( mentionID.charAt( 0 ) != options.marker ) {
 		if ( mentionID.charAt( 0 ) != options.marker ) {
 			/**
 			/**
-			 * The feed item id must start with the marker character.
+			 * The feed item ID must start with the marker character.
 			 *
 			 *
 			 * Correct mention feed setting:
 			 * Correct mention feed setting:
 			 *
 			 *
@@ -135,11 +136,11 @@ export default class MentionCommand extends Command {
 
 
 			attributesWithMention.set( 'mention', mention );
 			attributesWithMention.set( 'mention', mention );
 
 
-			// Replace range with a text with mention.
+			// Replace a range with the text with a mention.
 			writer.remove( range );
 			writer.remove( range );
 			writer.insertText( mentionText, attributesWithMention, range.start );
 			writer.insertText( mentionText, attributesWithMention, range.start );
 
 
-			// Insert space after a mention.
+			// Insert a space after the mention.
 			writer.insertText( ' ', currentAttributes, model.document.selection.focus );
 			writer.insertText( ' ', currentAttributes, model.document.selection.focus );
 		} );
 		} );
 	}
 	}

+ 20 - 19
packages/ckeditor5-mention/src/mentionediting.js

@@ -37,7 +37,7 @@ export default class MentionEditing extends Plugin {
 		const model = editor.model;
 		const model = editor.model;
 		const doc = model.document;
 		const doc = model.document;
 
 
-		// Allow mention attribute on all text nodes.
+		// Allow the mention attribute on all text nodes.
 		model.schema.extend( '$text', { allowAttributes: 'mention' } );
 		model.schema.extend( '$text', { allowAttributes: 'mention' } );
 
 
 		editor.conversion.for( 'upcast' ).elementToAttribute( {
 		editor.conversion.for( 'upcast' ).elementToAttribute( {
@@ -70,7 +70,7 @@ export function _addMentionAttributes( baseMentionData, data ) {
 }
 }
 
 
 /**
 /**
- * Creates mention attribute value from provided view element and optional data.
+ * Creates a mention attribute value from the provided view element and optional data.
  *
  *
  * This function is exposed as
  * This function is exposed as
  * {@link module:mention/mention~Mention#toMentionAttribute `editor.plugins.get( 'Mention' ).toMentionAttribute()`}.
  * {@link module:mention/mention~Mention#toMentionAttribute `editor.plugins.get( 'Mention' ).toMentionAttribute()`}.
@@ -98,7 +98,7 @@ export function _toMentionAttribute( viewElementOrMention, data ) {
 	return _addMentionAttributes( baseMentionData, data );
 	return _addMentionAttributes( baseMentionData, data );
 }
 }
 
 
-// Creates mention element from mention data.
+// Creates a mention element from the mention data.
 //
 //
 // @param {Object} mention
 // @param {Object} mention
 // @param {module:engine/view/downcastwriter~DowncastWriter} viewWriter
 // @param {module:engine/view/downcastwriter~DowncastWriter} viewWriter
@@ -121,11 +121,11 @@ function createViewMentionElement( mention, viewWriter ) {
 	return viewWriter.createAttributeElement( 'span', attributes, options );
 	return viewWriter.createAttributeElement( 'span', attributes, options );
 }
 }
 
 
-// Model post-fixer that disallows typing with selection when selection is placed after the text node with mention attribute.
+// Model post-fixer that disallows typing with selection when the selection is placed after the text node with the mention attribute.
 //
 //
 // @param {module:engine/model/writer~Writer} writer
 // @param {module:engine/model/writer~Writer} writer
 // @param {module:engine/model/document~Document} doc
 // @param {module:engine/model/document~Document} doc
-// @returns {Boolean} Returns true if selection was fixed.
+// @returns {Boolean} Returns `true` if the selection was fixed.
 function selectionMentionAttributePostFixer( writer, doc ) {
 function selectionMentionAttributePostFixer( writer, doc ) {
 	const selection = doc.selection;
 	const selection = doc.selection;
 	const focus = selection.focus;
 	const focus = selection.focus;
@@ -141,33 +141,33 @@ function selectionMentionAttributePostFixer( writer, doc ) {
 	}
 	}
 }
 }
 
 
-// Model post-fixer that removes mention attribute from modified text node.
+// Model post-fixer that removes the mention attribute from the modified text node.
 //
 //
 // @param {module:engine/model/writer~Writer} writer
 // @param {module:engine/model/writer~Writer} writer
 // @param {module:engine/model/document~Document} doc
 // @param {module:engine/model/document~Document} doc
-// @returns {Boolean} Returns true if selection was fixed.
+// @returns {Boolean} Returns `true` if the selection was fixed.
 function removePartialMentionPostFixer( writer, doc, schema ) {
 function removePartialMentionPostFixer( writer, doc, schema ) {
 	const changes = doc.differ.getChanges();
 	const changes = doc.differ.getChanges();
 
 
 	let wasChanged = false;
 	let wasChanged = false;
 
 
 	for ( const change of changes ) {
 	for ( const change of changes ) {
-		// Check text node on current position;
+		// Checks the text node on the current position.
 		const position = change.position;
 		const position = change.position;
 
 
 		if ( change.name == '$text' ) {
 		if ( change.name == '$text' ) {
 			const nodeAfterInsertedTextNode = position.textNode && position.textNode.nextSibling;
 			const nodeAfterInsertedTextNode = position.textNode && position.textNode.nextSibling;
 
 
-			// Check textNode where the change occurred.
+			// Checks the text node where the change occurred.
 			wasChanged = checkAndFix( position.textNode, writer ) || wasChanged;
 			wasChanged = checkAndFix( position.textNode, writer ) || wasChanged;
 
 
-			// Occurs on paste occurs inside a text node with mention.
+			// Occurs on paste inside a text node with mention.
 			wasChanged = checkAndFix( nodeAfterInsertedTextNode, writer ) || wasChanged;
 			wasChanged = checkAndFix( nodeAfterInsertedTextNode, writer ) || wasChanged;
 			wasChanged = checkAndFix( position.nodeBefore, writer ) || wasChanged;
 			wasChanged = checkAndFix( position.nodeBefore, writer ) || wasChanged;
 			wasChanged = checkAndFix( position.nodeAfter, writer ) || wasChanged;
 			wasChanged = checkAndFix( position.nodeAfter, writer ) || wasChanged;
 		}
 		}
 
 
-		// Check text nodes in inserted elements (might occur when splitting paragraph or pasting content inside text with mention).
+		// Checks text nodes in inserted elements (might occur when splitting a paragraph or pasting content inside text with mention).
 		if ( change.name != '$text' && change.type == 'insert' ) {
 		if ( change.name != '$text' && change.type == 'insert' ) {
 			const insertedNode = position.nodeAfter;
 			const insertedNode = position.nodeAfter;
 
 
@@ -188,11 +188,12 @@ function removePartialMentionPostFixer( writer, doc, schema ) {
 	return wasChanged;
 	return wasChanged;
 }
 }
 
 
-// This post-fixer will extend attribute applied on part of a mention so a whole text node of a mention will have added attribute.
+// This post-fixer will extend the attribute applied on the part of the mention so the whole text node of the mention will have
+// the added attribute.
 //
 //
 // @param {module:engine/model/writer~Writer} writer
 // @param {module:engine/model/writer~Writer} writer
 // @param {module:engine/model/document~Document} doc
 // @param {module:engine/model/document~Document} doc
-// @returns {Boolean} Returns true if selection was fixed.
+// @returns {Boolean} Returns `true` if the selection was fixed.
 function extendAttributeOnMentionPostFixer( writer, doc ) {
 function extendAttributeOnMentionPostFixer( writer, doc ) {
 	const changes = doc.differ.getChanges();
 	const changes = doc.differ.getChanges();
 
 
@@ -200,9 +201,9 @@ function extendAttributeOnMentionPostFixer( writer, doc ) {
 
 
 	for ( const change of changes ) {
 	for ( const change of changes ) {
 		if ( change.type === 'attribute' && change.attributeKey != 'mention' ) {
 		if ( change.type === 'attribute' && change.attributeKey != 'mention' ) {
-			// Check node at the left side of a range...
+			// Checks the node on the left side of the range...
 			const nodeBefore = change.range.start.nodeBefore;
 			const nodeBefore = change.range.start.nodeBefore;
-			// ... and on right side of range.
+			// ... and on the right side of the range.
 			const nodeAfter = change.range.end.nodeAfter;
 			const nodeAfter = change.range.end.nodeAfter;
 
 
 			for ( const node of [ nodeBefore, nodeAfter ] ) {
 			for ( const node of [ nodeBefore, nodeAfter ] ) {
@@ -218,10 +219,10 @@ function extendAttributeOnMentionPostFixer( writer, doc ) {
 	return wasChanged;
 	return wasChanged;
 }
 }
 
 
-// Checks if node has correct mention attribute if present.
-// Returns true if node is text and has a mention attribute which text does not match expected mention text.
+// Checks if a node has a correct mention attribute if present.
+// Returns `true` if the node is text and has a mention attribute whose text does not match the expected mention text.
 //
 //
-// @param {module:engine/model/node~Node} node a node to check
+// @param {module:engine/model/node~Node} node The node to check.
 // @returns {Boolean}
 // @returns {Boolean}
 function isBrokenMentionNode( node ) {
 function isBrokenMentionNode( node ) {
 	if ( !node || !( node.is( 'text' ) || node.is( 'textProxy' ) ) || !node.hasAttribute( 'mention' ) ) {
 	if ( !node || !( node.is( 'text' ) || node.is( 'textProxy' ) ) || !node.hasAttribute( 'mention' ) ) {
@@ -236,7 +237,7 @@ function isBrokenMentionNode( node ) {
 	return text != expectedText;
 	return text != expectedText;
 }
 }
 
 
-// Fixes mention on text node it needs a fix.
+// Fixes a mention on a text node if it needs a fix.
 //
 //
 // @param {module:engine/model/text~Text} textNode
 // @param {module:engine/model/text~Text} textNode
 // @param {module:engine/model/writer~Writer} writer
 // @param {module:engine/model/writer~Writer} writer

+ 30 - 29
packages/ckeditor5-mention/src/mentionui.js

@@ -44,14 +44,14 @@ export default class MentionUI extends Plugin {
 		super( editor );
 		super( editor );
 
 
 		/**
 		/**
-		 * The balloon panel view, containing the mention view.
+		 * The balloon panel view containing the mention view.
 		 *
 		 *
 		 * @type {module:ui/panel/balloon/balloonpanelview~BalloonPanelView}
 		 * @type {module:ui/panel/balloon/balloonpanelview~BalloonPanelView}
 		 */
 		 */
 		this.panelView = this._creatPanelView();
 		this.panelView = this._creatPanelView();
 
 
 		/**
 		/**
-		 * The mentions view.
+		 * The mention view.
 		 *
 		 *
 		 * @type {module:mention/ui/mentionsview~MentionsView}
 		 * @type {module:mention/ui/mentionsview~MentionsView}
 		 * @private
 		 * @private
@@ -59,7 +59,7 @@ export default class MentionUI extends Plugin {
 		this._mentionsView = this._createMentionView();
 		this._mentionsView = this._createMentionView();
 
 
 		/**
 		/**
-		 * Stores mentions feeds configurations.
+		 * Stores mention feeds configurations.
 		 *
 		 *
 		 * @type {Map<String, Object>}
 		 * @type {Map<String, Object>}
 		 * @private
 		 * @private
@@ -77,7 +77,7 @@ export default class MentionUI extends Plugin {
 		this.editor.editing.view.document.on( 'keydown', ( evt, data ) => {
 		this.editor.editing.view.document.on( 'keydown', ( evt, data ) => {
 			if ( isHandledKey( data.keyCode ) && this.panelView.isVisible ) {
 			if ( isHandledKey( data.keyCode ) && this.panelView.isVisible ) {
 				data.preventDefault();
 				data.preventDefault();
-				evt.stop(); // Required for enter overriding.
+				evt.stop(); // Required for Enter key overriding.
 
 
 				if ( data.keyCode == keyCodes.arrowdown ) {
 				if ( data.keyCode == keyCodes.arrowdown ) {
 					this._mentionsView.selectNext();
 					this._mentionsView.selectNext();
@@ -95,7 +95,7 @@ export default class MentionUI extends Plugin {
 					this._hidePanelAndRemoveMarker();
 					this._hidePanelAndRemoveMarker();
 				}
 				}
 			}
 			}
-		}, { priority: 'highest' } ); // Required to override enter.
+		}, { priority: 'highest' } ); // Required to override the Enter key.
 
 
 		// Close the #panelView upon clicking outside of the plugin UI.
 		// Close the #panelView upon clicking outside of the plugin UI.
 		clickOutsideHandler( {
 		clickOutsideHandler( {
@@ -124,7 +124,7 @@ export default class MentionUI extends Plugin {
 				 *
 				 *
 				 * @error mentionconfig-incorrect-marker
 				 * @error mentionconfig-incorrect-marker
 				 */
 				 */
-				throw new CKEditorError( 'mentionconfig-incorrect-marker: The marker must be provided and be a single character.' );
+				throw new CKEditorError( 'mentionconfig-incorrect-marker: The marker must be provided and it must be a single character.' );
 			}
 			}
 
 
 			const minimumCharacters = mentionDescription.minimumCharacters || 0;
 			const minimumCharacters = mentionDescription.minimumCharacters || 0;
@@ -238,7 +238,7 @@ export default class MentionUI extends Plugin {
 	}
 	}
 
 
 	/**
 	/**
-	 * Returns item renderer for marker.
+	 * Returns item renderer for the marker.
 	 *
 	 *
 	 * @private
 	 * @private
 	 * @param {String} marker
 	 * @param {String} marker
@@ -251,7 +251,7 @@ export default class MentionUI extends Plugin {
 	}
 	}
 
 
 	/**
 	/**
-	 * Returns a promise that resolves with autocomplete items for given text.
+	 * Returns a promise that resolves with autocomplete items for a given text.
 	 *
 	 *
 	 * @param {String} marker
 	 * @param {String} marker
 	 * @param {String} feedText
 	 * @param {String} feedText
@@ -265,7 +265,7 @@ export default class MentionUI extends Plugin {
 	}
 	}
 
 
 	/**
 	/**
-	 * Registers a text watcher for marker.
+	 * Registers a text watcher for the marker.
 	 *
 	 *
 	 * @private
 	 * @private
 	 * @param {String} marker
 	 * @param {String} marker
@@ -293,7 +293,7 @@ export default class MentionUI extends Plugin {
 
 
 			const matchedTextLength = marker.length + feedText.length;
 			const matchedTextLength = marker.length + feedText.length;
 
 
-			// create marker range
+			// Create a marker range.
 			const start = selection.focus.getShiftedBy( -matchedTextLength );
 			const start = selection.focus.getShiftedBy( -matchedTextLength );
 			const end = selection.focus.getShiftedBy( -feedText.length );
 			const end = selection.focus.getShiftedBy( -feedText.length );
 
 
@@ -337,7 +337,7 @@ export default class MentionUI extends Plugin {
 	}
 	}
 
 
 	/**
 	/**
-	 * Returns registered text watcher for marker.
+	 * Returns the registered text watcher for the marker.
 	 *
 	 *
 	 * @private
 	 * @private
 	 * @param {String} marker
 	 * @param {String} marker
@@ -350,7 +350,7 @@ export default class MentionUI extends Plugin {
 	}
 	}
 
 
 	/**
 	/**
-	 * Shows the {@link #panelView}. If panel is already visible it will reposition it.
+	 * Shows the {@link #panelView}. If the panel is already visible, it will reposition it.
 	 *
 	 *
 	 * @private
 	 * @private
 	 */
 	 */
@@ -361,7 +361,7 @@ export default class MentionUI extends Plugin {
 	}
 	}
 
 
 	/**
 	/**
-	 * Hides the {@link #panelView} and remove 'mention' marker from markers collection.
+	 * Hides the {@link #panelView} and removes the 'mention' marker from the markers collection.
 	 *
 	 *
 	 * @private
 	 * @private
 	 */
 	 */
@@ -371,7 +371,8 @@ export default class MentionUI extends Plugin {
 		}
 		}
 
 
 		this.panelView.unpin();
 		this.panelView.unpin();
-		// Make last matched position on panel view undefined so the #_getBalloonPanelPositionData() will return all positions on next call.
+		// Make the last matched position on panel view undefined so the #_getBalloonPanelPositionData() method will return all positions
+		// on the next call.
 		this.panelView.position = undefined;
 		this.panelView.position = undefined;
 		this.panelView.hide();
 		this.panelView.hide();
 	}
 	}
@@ -415,10 +416,10 @@ export default class MentionUI extends Plugin {
 	}
 	}
 
 
 	/**
 	/**
-	 * Creates position options object used to position the balloon panel.
+	 * Creates a position options object used to position the balloon panel.
 	 *
 	 *
 	 * @param {module:engine/model/markercollection~Marker} mentionMarker
 	 * @param {module:engine/model/markercollection~Marker} mentionMarker
-	 * @param {String|undefined} positionName Name of last matched position name.
+	 * @param {String|undefined} positionName The name of the last matched position name.
 	 * @returns {module:utils/dom/position~Options}
 	 * @returns {module:utils/dom/position~Options}
 	 * @private
 	 * @private
 	 */
 	 */
@@ -452,12 +453,12 @@ export default class MentionUI extends Plugin {
 	}
 	}
 }
 }
 
 
-// Returns balloon positions data callbacks.
+// Returns the balloon positions data callbacks.
 //
 //
 // @returns {Array.<module:utils/dom/position~Position>}
 // @returns {Array.<module:utils/dom/position~Position>}
 function getBalloonPanelPositions( positionName ) {
 function getBalloonPanelPositions( positionName ) {
 	const positions = {
 	const positions = {
-		// Positions panel to the south of caret rect.
+		// Positions the panel to the southeast of the caret rectangle.
 		'caret_se': targetRect => {
 		'caret_se': targetRect => {
 			return {
 			return {
 				top: targetRect.bottom + VERTICAL_SPACING,
 				top: targetRect.bottom + VERTICAL_SPACING,
@@ -466,7 +467,7 @@ function getBalloonPanelPositions( positionName ) {
 			};
 			};
 		},
 		},
 
 
-		// Positions panel to the north of caret rect.
+		// Positions the panel to the northeast of the caret rectangle.
 		'caret_ne': ( targetRect, balloonRect ) => {
 		'caret_ne': ( targetRect, balloonRect ) => {
 			return {
 			return {
 				top: targetRect.top - balloonRect.height - VERTICAL_SPACING,
 				top: targetRect.top - balloonRect.height - VERTICAL_SPACING,
@@ -475,7 +476,7 @@ function getBalloonPanelPositions( positionName ) {
 			};
 			};
 		},
 		},
 
 
-		// Positions panel to the south of caret rect.
+		// Positions the panel to the southwest of the caret rectangle.
 		'caret_sw': ( targetRect, balloonRect ) => {
 		'caret_sw': ( targetRect, balloonRect ) => {
 			return {
 			return {
 				top: targetRect.bottom + VERTICAL_SPACING,
 				top: targetRect.bottom + VERTICAL_SPACING,
@@ -484,7 +485,7 @@ function getBalloonPanelPositions( positionName ) {
 			};
 			};
 		},
 		},
 
 
-		// Positions panel to the north of caret rect.
+		// Positions the panel to the northwest of the caret rect.
 		'caret_nw': ( targetRect, balloonRect ) => {
 		'caret_nw': ( targetRect, balloonRect ) => {
 			return {
 			return {
 				top: targetRect.top - balloonRect.height - VERTICAL_SPACING,
 				top: targetRect.top - balloonRect.height - VERTICAL_SPACING,
@@ -494,14 +495,14 @@ function getBalloonPanelPositions( positionName ) {
 		}
 		}
 	};
 	};
 
 
-	// Return only last position if it was matched to prevent panel from jumping after first match.
+	// Returns only the last position if it was matched to prevent the panel from jumping after the first match.
 	if ( positions.hasOwnProperty( positionName ) ) {
 	if ( positions.hasOwnProperty( positionName ) ) {
 		return [
 		return [
 			positions[ positionName ]
 			positions[ positionName ]
 		];
 		];
 	}
 	}
 
 
-	// As default return all positions callbacks.
+	// By default return all position callbacks.
 	return [
 	return [
 		positions.caret_se,
 		positions.caret_se,
 		positions.caret_ne,
 		positions.caret_ne,
@@ -510,7 +511,7 @@ function getBalloonPanelPositions( positionName ) {
 	];
 	];
 }
 }
 
 
-// Creates a regex pattern for marker.
+// Creates a regex pattern for the marker.
 //
 //
 // @param {String} marker
 // @param {String} marker
 // @param {Number} minimumCharacters
 // @param {Number} minimumCharacters
@@ -521,7 +522,7 @@ function createPattern( marker, minimumCharacters ) {
 	return `(^| )(\\${ marker })([_a-zA-Z0-9À-ž]${ numberOfCharacters }?)$`;
 	return `(^| )(\\${ marker })([_a-zA-Z0-9À-ž]${ numberOfCharacters }?)$`;
 }
 }
 
 
-// Creates a test callback for marker to be used in text watcher instance.
+// Creates a test callback for the marker to be used in the text watcher instance.
 //
 //
 // @param {String} marker
 // @param {String} marker
 // @param {Number} minimumCharacters
 // @param {Number} minimumCharacters
@@ -532,7 +533,7 @@ function createTestCallback( marker, minimumCharacters ) {
 	return text => regExp.test( text );
 	return text => regExp.test( text );
 }
 }
 
 
-// Creates a text watcher matcher for marker.
+// Creates a text matcher from the marker.
 //
 //
 // @param {String} marker
 // @param {String} marker
 // @returns {Function}
 // @returns {Function}
@@ -549,11 +550,11 @@ function createTextMatcher( marker ) {
 	};
 	};
 }
 }
 
 
-// Default feed callback
+// The default feed callback.
 function createFeedCallback( feedItems ) {
 function createFeedCallback( feedItems ) {
 	return feedText => {
 	return feedText => {
 		const filteredItems = feedItems
 		const filteredItems = feedItems
-		// Make default mention feed case-insensitive.
+		// Make the default mention feed case-insensitive.
 			.filter( item => {
 			.filter( item => {
 				// Item might be defined as object.
 				// Item might be defined as object.
 				const itemId = typeof item == 'string' ? item : String( item.id );
 				const itemId = typeof item == 'string' ? item : String( item.id );
@@ -568,7 +569,7 @@ function createFeedCallback( feedItems ) {
 	};
 	};
 }
 }
 
 
-// Checks if given key code is handled by the mention ui.
+// Checks if a given key code is handled by the mention UI.
 //
 //
 // @param {Number}
 // @param {Number}
 // @returns {Boolean}
 // @returns {Boolean}

+ 13 - 13
packages/ckeditor5-mention/src/textwatcher.js

@@ -11,10 +11,10 @@ import mix from '@ckeditor/ckeditor5-utils/src/mix';
 import EmitterMixin from '@ckeditor/ckeditor5-utils/src/emittermixin';
 import EmitterMixin from '@ckeditor/ckeditor5-utils/src/emittermixin';
 
 
 /**
 /**
- * Text watcher feature.
+ * The text watcher feature.
  *
  *
- * Fires {@link module:mention/textwatcher~TextWatcher#event:matched matched} and
- * {@link module:mention/textwatcher~TextWatcher#event:unmatched unmatched} events on typing or selection changes.
+ * Fires {@link module:mention/textwatcher~TextWatcher#event:matched `matched`} and
+ * {@link module:mention/textwatcher~TextWatcher#event:unmatched `unmatched`} events on typing or selection changes.
  *
  *
  * @private
  * @private
  */
  */
@@ -22,8 +22,8 @@ export default class TextWatcher {
 	/**
 	/**
 	 * Creates a text watcher instance.
 	 * Creates a text watcher instance.
 	 * @param {module:core/editor/editor~Editor} editor
 	 * @param {module:core/editor/editor~Editor} editor
-	 * @param {Function} testCallback Function used to match the text.
-	 * @param {Function} textMatcherCallback Function used to process matched text.
+	 * @param {Function} testCallback The function used to match the text.
+	 * @param {Function} textMatcherCallback The function used to process matched text.
 	 */
 	 */
 	constructor( editor, testCallback, textMatcherCallback ) {
 	constructor( editor, testCallback, textMatcherCallback ) {
 		this.editor = editor;
 		this.editor = editor;
@@ -36,7 +36,7 @@ export default class TextWatcher {
 	}
 	}
 
 
 	/**
 	/**
-	 * Last matched text.
+	 * The last matched text.
 	 *
 	 *
 	 * @property {String}
 	 * @property {String}
 	 */
 	 */
@@ -45,7 +45,7 @@ export default class TextWatcher {
 	}
 	}
 
 
 	/**
 	/**
-	 * Starts listening the editor for typing & selection events.
+	 * Starts listening to the editor for typing and selection events.
 	 *
 	 *
 	 * @private
 	 * @private
 	 */
 	 */
@@ -53,7 +53,7 @@ export default class TextWatcher {
 		const editor = this.editor;
 		const editor = this.editor;
 
 
 		editor.model.document.selection.on( 'change', ( evt, { directChange } ) => {
 		editor.model.document.selection.on( 'change', ( evt, { directChange } ) => {
-			// The indirect changes (ie on typing) are handled in document's change event.
+			// Indirect changes (i.e. on typing) are handled in the document's change event.
 			if ( !directChange ) {
 			if ( !directChange ) {
 				return;
 				return;
 			}
 			}
@@ -85,7 +85,7 @@ export default class TextWatcher {
 
 
 		if ( !textHasMatch && this.hasMatch ) {
 		if ( !textHasMatch && this.hasMatch ) {
 			/**
 			/**
-			 * Fired whenever text doesn't match anymore. Fired only when text matcher was matched.
+			 * Fired whenever the text does not match anymore. Fired only when the text watcher found a match.
 			 *
 			 *
 			 * @event unmatched
 			 * @event unmatched
 			 */
 			 */
@@ -98,7 +98,7 @@ export default class TextWatcher {
 			const matched = this.textMatcher( text );
 			const matched = this.textMatcher( text );
 
 
 			/**
 			/**
-			 * Fired whenever text matcher was matched.
+			 * Fired whenever the text watcher found a match.
 			 *
 			 *
 			 * @event matched
 			 * @event matched
 			 */
 			 */
@@ -109,14 +109,14 @@ export default class TextWatcher {
 	/**
 	/**
 	 * Returns the text before the caret from the current selection block.
 	 * Returns the text before the caret from the current selection block.
 	 *
 	 *
-	 * @returns {String|undefined} Text from block or undefined if selection is not collapsed.
+	 * @returns {String|undefined} The text from the block or undefined if the selection is not collapsed.
 	 * @private
 	 * @private
 	 */
 	 */
 	_getText() {
 	_getText() {
 		const editor = this.editor;
 		const editor = this.editor;
 		const selection = editor.model.document.selection;
 		const selection = editor.model.document.selection;
 
 
-		// Do nothing if selection is not collapsed.
+		// Do nothing if the selection is not collapsed.
 		if ( !selection.isCollapsed ) {
 		if ( !selection.isCollapsed ) {
 			return;
 			return;
 		}
 		}
@@ -128,7 +128,7 @@ export default class TextWatcher {
 }
 }
 
 
 /**
 /**
- * Returns whole text from given range by adding all data from text nodes together.
+ * Returns the whole text from a given range by adding all data from the text nodes together.
  *
  *
  * @protected
  * @protected
  * @param {module:engine/model/range~Range} range
  * @param {module:engine/model/range~Range} range