瀏覽代碼

Docs: Highlight documentation reviewed. [skip ci]

Anna Tomanek 7 年之前
父節點
當前提交
5ae79a7e07

+ 15 - 15
packages/ckeditor5-highlight/docs/features/highlight.md

@@ -5,7 +5,7 @@ category: features
 
 {@snippet features/build-highlight-source}
 
-The {@link module:highlight/highlight~Highlight} feature offers a text marking tools that help content authors speed up their work, e.g. reviewing content or marking it for the future reference. It uses inline `<marker>` elements in the view, supports both markers (background color) and pens (text color), and comes with a flexible configuration.
+The {@link module:highlight/highlight~Highlight} feature offers text marking tools that help content authors speed up their work, for example when reviewing content or marking it for future reference. It uses inline `<mark>` elements in the view, supports both markers (background color) and pens (text color), and comes with a flexible configuration.
 
 ## Demo
 
@@ -53,7 +53,7 @@ ClassicEditor
 
 ### Inline buttons
 
-Instead of using the (default) `highlight`, the feature also supports a configuration with separate buttons directly in the toolbar:
+Instead of using the (default) `highlight` button, the feature also supports a configuration with separate buttons available directly in the toolbar:
 
 ```js
 ClassicEditor
@@ -81,9 +81,9 @@ ClassicEditor
 	See the plugin {@link module:highlight/highlight~HighlightConfig#options options} to learn more about defaults.
 </info-box>
 
-#### Using CSS Variables
+#### Using CSS variables
 
-The highlight 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 [stylesheet](https://github.com/ckeditor/ckeditor5-highlight/blob/master/theme/highlight.css). Thanks to that, both the UI and the content styles share the same color definitions, which can be easily customized:
+The highlight 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 [stylesheet](https://github.com/ckeditor/ckeditor5-highlight/blob/master/theme/highlight.css). Thanks to that, both the UI and the content styles share the same color definitions which can be easily customized:
 
 ```css
 :root {
@@ -102,7 +102,7 @@ The highlight feature is using the power of [CSS variables](https://developer.mo
 
 #### Inline color definitions
 
-It is possible to use the inline color values in the `rgba(R, G, B, A)`, `#RRGGBB[AA]` or `hsla(H, S, L, A)` formats instead of CSS variables. To do that, customize the {@link module:highlight/highlight~HighlightConfig#options options} and define the `color` property for each option:
+It is possible to use inline color values in the `rgba(R, G, B, A)`, `#RRGGBB[AA]` or `hsla(H, S, L, A)` formats instead of CSS variables. To do that, customize the {@link module:highlight/highlight~HighlightConfig#options options} and define the `color` property for each option:
 
 ```js
 ClassicEditor
@@ -140,7 +140,7 @@ ClassicEditor
 	.catch( ... );
 ```
 
-Then, update the classes in the style sheet so the content corresponds to the UI of the editor. It is recommended for the UI buttons and the actual highlights in the text to share the same colors.
+Then, update the classes in the stylesheet so the content corresponds to the UI of the editor. It is recommended for the UI buttons and the actual highlights in the text to share the same colors.
 
 ```css
 .marker-green {
@@ -160,7 +160,7 @@ Then, update the classes in the style sheet so the content corresponds to the UI
 
 To add this feature to your editor install the [`@ckeditor/ckeditor5-highlight`](https://www.npmjs.com/package/@ckeditor/ckeditor5-highlight) package:
 
-```
+```bash
 npm install --save @ckeditor/ckeditor5-highlight
 ```
 
@@ -197,7 +197,7 @@ The {@link module:highlight/highlight~Highlight} plugin registers:
 	editor.execute( 'highlight', { value: 'yellowMarker' } );
 	```
 
-	The `value` corresponds to the `model` property in configuration object. For the default configuration:
+	The `value` corresponds to the `model` property in the configuration object. For the default configuration:
 
 	```js
 	highlight.options = [
@@ -212,14 +212,14 @@ The {@link module:highlight/highlight~Highlight} plugin registers:
 
 	the `highlight` command will accept the corresponding strings as values:
 
-	* `'yellowMarker'` – available as a `'highlight:yellowMarker'` button,
-	* `'greenMarker'` – available as a `'highlight:greenMarker'` button,
-	* `'pinkMarker'` – available as a `'highlight:pinkMarker'` button,
-	* `'blueMarker'` – available as a `'highlight:blueMarker'` button,
-	* `'redPen'` – available as a `'highlight:redPen'` button,
-	* `'greenPen'` – available as a `'highlight:greenPen'` button.
+	* `'yellowMarker'` &ndash; available as the `'highlight:yellowMarker'` button,
+	* `'greenMarker'` &ndash; available as the `'highlight:greenMarker'` button,
+	* `'pinkMarker'` &ndash; available as the `'highlight:pinkMarker'` button,
+	* `'blueMarker'` &ndash; available as the `'highlight:blueMarker'` button,
+	* `'redPen'` &ndash; available as the `'highlight:redPen'` button,
+	* `'greenPen'` &ndash; available as the `'highlight:greenPen'` button.
 
-	passing an empty `value` will remove any `highlight` from the selection:
+	Passing an empty `value` will remove any `highlight` from the selection:
 
 	```js
 	editor.execute( 'highlight' );

+ 17 - 15
packages/ckeditor5-highlight/src/highlight.js

@@ -18,7 +18,7 @@ import HighlightUI from './highlightui';
  * It loads the {@link module:highlight/highlightediting~HighlightEditing} and
  * {@link module:highlight/highlightui~HighlightUI} plugins.
  *
- * Read more about the feature in the {@glink api/highlight highlight package} page.
+ * For a detailed overview, check the {@glink features/highlight highlight feature} documentation.
  *
  * @extends module:core/plugin~Plugin
  */
@@ -39,7 +39,7 @@ export default class Highlight extends Plugin {
 }
 
 /**
- * The highlight option descriptor. See the {@link module:highlight/highlight~HighlightConfig} to learn more.
+ * The highlight option descriptor. See {@link module:highlight/highlight~HighlightConfig} to learn more.
  *
  *		{
  *			model: 'pinkMarker',
@@ -52,13 +52,14 @@ export default class Highlight extends Plugin {
  * @typedef {Object} module:highlight/highlight~HighlightOption
  * @property {String} title The user-readable title of the option.
  * @property {String} model The unique attribute value in the model.
- * @property {String} color The CSS var() used for the highlighter. The color is used in the user interface to represent the highlighter.
- * There is possibility to use default color format like rgb, hex or hsl, but you need to care about color of `<mark>`
+ * @property {String} color The CSS `var()` used for the highlighter. The color is used in the user interface to represent the highlighter.
+ * There is a possibility to use the default color format like rgb, hex or hsl, but you need to care about the color of `<mark>`
  * by adding CSS classes definition.
  * @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'` – uses the `color` as a `background-color` style,
- * - `'pen'` – uses the `color` as a font `color` style.
+ *
+ * * `'marker'` &ndash; Uses the `color` as the `background-color` style,
+ * * `'pen'` &ndash; Uses the `color` as the font `color` style.
  */
 
 /**
@@ -70,11 +71,11 @@ export default class Highlight extends Plugin {
  */
 
 /**
- * The configuration of the {@link module:highlight/highlight~Highlight Highlight feature}.
+ * The configuration of the {@link module:highlight/highlight~Highlight highlight feature}.
  *
  *		ClassicEditor
  *			.create( editorElement, {
- * 				highlight:  ... // Highlight feature config.
+ * 				highlight:  ... // Highlight feature configuration.
  *			} )
  *			.then( ... )
  *			.catch( ... );
@@ -85,7 +86,7 @@ export default class Highlight extends Plugin {
  */
 
 /**
- * The available highlighters options. The default value is:
+ * The available highlight options. The default value is:
  *
  *		options: [
  *			{
@@ -133,10 +134,11 @@ export default class Highlight extends Plugin {
  *		]
  *
  * 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`.
  *
- * **Note**: The highlight feature provides a style sheet with the CSS classes and corresponding colors defined
+ * * `'marker'` &ndash; Rendered as a `<mark>` element, styled with the `background-color`.
+ * * `'pen'` &ndash; Rendered as a `<mark>` element, styled with the font `color`.
+ *
+ * **Note**: The highlight feature provides a stylesheet with the CSS classes and corresponding colors defined
  * as CSS variables.
  *
  *		:root {
@@ -155,13 +157,13 @@ export default class Highlight extends Plugin {
  *		.pen-red { ... }
  *		.pen-green { ... }
  *
- * **Note**: It is possible to define the `color` property directly as `rgba(R, G, B, A)`,
+ * It is possible to define the `color` property directly as `rgba(R, G, B, A)`,
  * `#RRGGBB[AA]` or `hsla(H, S, L, A)`. In such situation, the color will **only** apply to the UI of
  * the editor and the `<mark>` elements in the content must be styled by custom classes provided by
- * a dedicated style sheet.
+ * a dedicated stylesheet.
  *
  * **Note**: It is recommended for the `color` property to correspond to the class in the content
- * style sheet because it represents the highlighter in the user interface of the editor.
+ * stylesheet because it represents the highlighter in the user interface of the editor.
  *
  *		ClassicEditor
  *			.create( editorElement, {

+ 2 - 2
packages/ckeditor5-highlight/src/highlightcommand.js

@@ -16,7 +16,7 @@ import Range from '@ckeditor/ckeditor5-engine/src/model/range';
  *
  *		editor.execute( 'highlight', { value: 'greenMarker' } );
  *
- * **Note**: Executing the command without the value removes the attribute from the model. If the selection is collapsed
+ * **Note**: Executing the command without a 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.
  *
@@ -47,7 +47,7 @@ export default class HighlightCommand extends Command {
 	 *
 	 * @protected
 	 * @param {Object} [options] Options for the executed command.
-	 * @param {String} [options.value] a value to apply.
+	 * @param {String} [options.value] The value to apply.
 	 *
 	 * @fires execute
 	 */

+ 3 - 3
packages/ckeditor5-highlight/src/highlightediting.js

@@ -14,7 +14,7 @@ import HighlightCommand from './highlightcommand';
 /**
  * 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 the class attribute (`<span class="marker-green">...</span>`) depending
+ * as a `<mark>` element with a `class` attribute (`<mark class="marker-green">...</span>`) depending
  * on the {@link module:highlight/highlight~HighlightConfig configuration}.
  *
  * @extends module:core/plugin~Plugin
@@ -92,9 +92,9 @@ export default class HighlightEditing extends Plugin {
 	}
 }
 
-// Converts options array to a converter definition.
+// Converts the options array to a converter definition.
 //
-// @param {Array.<module:highlight/highlight~HighlightOption>} options Array with configured options.
+// @param {Array.<module:highlight/highlight~HighlightOption>} options An array with configured options.
 // @returns {module:engine/conversion/conversion~ConverterDefinition}
 function _buildDefinition( options ) {
 	const definition = {

+ 10 - 10
packages/ckeditor5-highlight/src/highlightui.js

@@ -22,10 +22,10 @@ import { createDropdown, addToolbarToDropdown } from '@ckeditor/ckeditor5-ui/src
 import './../theme/highlight.css';
 
 /**
- * The default Highlight UI plugin. It introduces:
+ * The default highlight UI plugin. It introduces:
  *
- * * the `'highlight'` dropdown,
- * * `'removeHighlight'` and `'highlight:*'` buttons.
+ * * The `'highlight'` dropdown,
+ * * The `'removeHighlight'` and `'highlight:*'` buttons.
  *
  * The default configuration includes the following buttons:
  *
@@ -94,7 +94,7 @@ export default class HighlightUI extends Plugin {
 	}
 
 	/**
-	 * Creates remove highlight button.
+	 * Creates the "Remove highlight" button.
 	 *
 	 * @private
 	 */
@@ -105,7 +105,7 @@ export default class HighlightUI extends Plugin {
 	}
 
 	/**
-	 * Creates toolbar button from provided highlight option.
+	 * Creates a toolbar button from the provided highlight option.
 	 *
 	 * @param {module:highlight/highlight~HighlightOption} option
 	 * @private
@@ -126,10 +126,10 @@ export default class HighlightUI extends Plugin {
 	/**
 	 * Internal method for creating highlight buttons.
 	 *
-	 * @param {String} name Name of a button.
-	 * @param {String} label Label for button.
-	 * @param {String} icon Button's icon.
-	 * @param {Function} [decorateButton=()=>{}] Additional method for extending button.
+	 * @param {String} name The name of the button.
+	 * @param {String} label The label for the button.
+	 * @param {String} icon The button icon.
+	 * @param {Function} [decorateButton=()=>{}] Additional method for extending the button.
 	 * @private
 	 */
 	_addButton( name, label, icon, value, decorateButton = () => {} ) {
@@ -159,7 +159,7 @@ export default class HighlightUI extends Plugin {
 	}
 
 	/**
-	 * Creates split button dropdown UI from provided highlight options.
+	 * Creates the split button dropdown UI from the provided highlight options.
 	 *
 	 * @param {Array.<module:highlight/highlight~HighlightOption>} options
 	 * @private