Docs: Improved the highlight package docs.

src/highlight.js

@@ -39,16 +39,25 @@ export default class Highlight extends Plugin {
 }
 
 /**
- * Highlight option descriptor.
+ * The highlight option descriptor. See the {@link module:highlight/highlight~HighlightConfig} to learn more.
+ *
+ *		{
+ *			model: 'pinkMarker',
+ *			class: 'marker-pink',
+ *			title: 'Pink Marker',
+ *			color: '#ff6fff',
+ *			type: 'marker'
+ *		}
  *
  * @typedef {Object} module:highlight/highlight~HighlightOption
  * @property {String} title The user-readable title of the option.
- * @property {String} model Attribute's unique value in the model.
- * @property {String} color Color used for highlighter. Should be coherent with `class` CSS setting.
- * @property {String} class CSS Class used on `mark` element in view. Should be coherent with `color` setting.
+ * @property {String} model The unique attribute value in the model.
+ * @property {String} color The color used for the highlighter. It should match the `class` CSS definition.
+ * The color is used in the user interface to represent the highlighter.
+ * @property {String} class The CSS class used on the `<mark>` element in the view. It should match the `color` setting.
  * @property {'marker'|'pen'} type The type of highlighter:
- * - "marker" - will use #color as highlight background,
- * - "pen" - will use #color as highlight font color.
+ * - `'marker'` – uses the `color` as a `background-color` style,
+ * - `'pen'` – uses the `color` as a font `color` style.
  */
 
 /**
@@ -75,14 +84,25 @@ export default class Highlight extends Plugin {
  */
 
 /**
- * Available highlighters options.
+ * The available highlighters options. The default value is:
+ *
+ *		options: [
+ *			{ model: 'marker', class: 'marker', title: 'Marker', color: '#ffff66', type: 'marker' },
+ *			{ model: 'greenMarker', class: 'marker-green', title: 'Green marker', color: '#66ff00', type: 'marker' },
+ *			{ model: 'pinkMarker', class: 'marker-pink', title: 'Pink marker', color: '#ff6fff', type: 'marker' },
+ *			{ model: 'redPen', class: 'pen-red', title: 'Red pen', color: '#ff2929', type: 'pen' },
+ *			{ model: 'bluePen', class: 'pen-blue', title: 'Blue pen', color: '#0091ff', type: 'pen' }
+ *		]
+ *
+ * There are two types of highlighters available:
+ * - `'marker'` - rendered as a `<mark>` element, styled with the `background-color`,
+ * - `'pen'` - rendered as a `<mark>` element, styled with the font `color`.
  *
- * There are two types of highlighters:
- * - 'marker' - rendered as `<mark>` element with defined background color.
- * - 'pen' - rendered as `<mark>` element with defined foreground (font) color.
+ * **Note**: A style sheet with CSS classes is required for the configuration to work properly.
+ * The highlight feature does not provide the actual styles by itself.
  *
- * **Note**: Each highlighter must have it's own CSS class defined to properly match content data.
- * Also it is advised that color value should match the values defined in content CSS stylesheet.
+ * **Note**: It is recommended that the `color` value should correspond to the class in the content
+ * style sheet. It represents the highlighter in the user interface of the editor.
  *
  *		ClassicEditor
  *			.create( editorElement, {

src/highlightcommand.js

@@ -12,12 +12,13 @@ import Range from '@ckeditor/ckeditor5-engine/src/model/range';
 
 /**
  * The highlight command. It is used by the {@link module:highlight/highlightediting~HighlightEditing highlight feature}
- * to apply text highlighting.
+ * to apply the text highlighting.
  *
  *		editor.execute( 'highlight', { value: 'greenMarker' } );
  *
- * **Note**: Executing the command without the value removes the attribute from the model. If selection is collapsed inside
- * text with highlight attribute the whole range with that attribute will be removed from the model.
+ * **Note**: Executing the command without the value removes the attribute from the model. If the selection is collapsed
+ * inside a text with the highlight attribute, the command will remove the attribute from the entire range
+ * of that text.
  *
  * @extends module:core/command~Command
  */
@@ -30,8 +31,8 @@ export default class HighlightCommand extends Command {
 		const doc = model.document;
 
 		/**
-		 * A value indicating whether the command is active. If the selection has highlight attribute
-		 * set the value will be set to highlight attribute value.
+		 * A value indicating whether the command is active. If the selection has some highlight attribute,
+		 * it corresponds to the value of that attribute.
 		 *
 		 * @observable
 		 * @readonly

src/highlightediting.js

@@ -13,9 +13,9 @@ import { attributeToElement } from '@ckeditor/ckeditor5-engine/src/conversion/tw
 import HighlightCommand from './highlightcommand';
 
 /**
- * The highlight editing feature. It introduces {@link module:highlight/highlightcommand~HighlightCommand command } and the `highlight`
+ * The highlight editing feature. It introduces the {@link module:highlight/highlightcommand~HighlightCommand command} and the `highlight`
  * attribute in the {@link module:engine/model/model~Model model} which renders in the {@link module:engine/view/view view}
- * as a `<mark>` element with a class attribute (`<span class="marker-green">...</span>`) depending
+ * as a `<mark>` element with the class attribute (`<span class="marker-green">...</span>`) depending
  * on the {@link module:highlight/highlight~HighlightConfig configuration}.
  *
  * @extends module:core/plugin~Plugin

src/highlightui.js

@@ -23,15 +23,20 @@ import { createDropdown, addToolbarToDropdown } from '@ckeditor/ckeditor5-ui/src
 import './../theme/highlight.css';
 
 /**
- * The default Highlight UI plugin. It introduces the `'highlightDropdown'` drop-down, `'removeHighlight'` and `'highlight:*'` buttons.
+ * The default Highlight UI plugin. It introduces:
+ * * the `'highlightDropdown'` drop-down,
+ * * `'removeHighlight'` and `'highlight:*'` buttons.
  *
- * The default configuration provides below buttons:
+ * The default configuration includes the following buttons:
  * * `'highlight:marker'`
  * * `'highlight:pinkMarker'`
  * * `'highlight:greenMarker'`
  * * `'highlight:redPen'`
  * * `'highlight:bluePen'`
  *
+ * See the {@link module:highlight/highlight~HighlightConfig#options configuration} to learn more
+ * about the defaults.
+ *
  * @extends module:core/plugin~Plugin
  */
 export default class HighlightUI extends Plugin {