瀏覽代碼

Docs: Various fixes and improvements in the documentation.

Aleksander Nowodzinski 7 年之前
父節點
當前提交
9140078764

+ 1 - 1
packages/ckeditor5-font/docs/_snippets/features/custom-font-family-options.js

@@ -8,7 +8,7 @@ ClassicEditor
 	.create( document.querySelector( '#snippet-custom-font-family-options' ), {
 		toolbar: {
 			items: [
-				'headings', '|', 'bulletedList', 'numberedList', 'fontFamily', 'undo', 'redo'
+				'headings', '|', 'fontFamily', 'bulletedList', 'numberedList', 'undo', 'redo'
 			],
 			viewportTopOffset: 60
 		},

+ 1 - 1
packages/ckeditor5-font/docs/_snippets/features/custom-font-size-named-options.js

@@ -8,7 +8,7 @@ ClassicEditor
 	.create( document.querySelector( '#snippet-custom-font-size-named-options' ), {
 		toolbar: {
 			items: [
-				'headings', '|', 'bulletedList', 'numberedList', 'fontSize', 'undo', 'redo'
+				'headings', '|', 'fontSize', 'bulletedList', 'numberedList', 'undo', 'redo'
 			],
 			viewportTopOffset: 60
 		},

+ 1 - 1
packages/ckeditor5-font/docs/_snippets/features/custom-font-size-numeric-options.js

@@ -8,7 +8,7 @@ ClassicEditor
 	.create( document.querySelector( '#snippet-custom-font-size-numeric-options' ), {
 		toolbar: {
 			items: [
-				'headings', '|', 'bulletedList', 'numberedList', 'fontSize', 'undo', 'redo'
+				'headings', '|', 'fontSize', 'bulletedList', 'numberedList', 'undo', 'redo'
 			],
 			viewportTopOffset: 60
 		},

+ 1 - 1
packages/ckeditor5-font/docs/_snippets/features/font.js

@@ -9,7 +9,7 @@ ClassicEditor
 	.create( document.querySelector( '#snippet-font' ), {
 		toolbar: {
 			items: [
-				'headings', '|', 'bulletedList', 'numberedList', 'fontSize', 'fontFamily', 'undo', 'redo'
+				'headings', '|', 'fontSize', 'fontFamily', '|', 'bulletedList', 'numberedList', 'undo', 'redo'
 			],
 			viewportTopOffset: 60
 		}

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

@@ -5,23 +5,19 @@ category: features
 
 {@snippet features/build-font-source}
 
-The {@link module:font/font~Font} feature enables support for:
-* setting font family - which allows to control font face of a text by inline `<span>` elements with a `font-family` CSS set in style attribute.
-* setting font size - which allows to control size of a text by inline `<span>` elements that have set either class or `font-size` CSS set in style attribute.
-
-The font features can be used independently by using:
-* {@link module:font/fontfamily~FontFamily} to control font face of a text.
-* {@link module:font/fontsize~FontSize} to control size of a text.
+The {@link module:font/font~Font} plugin enables the following features in the editor:
+* {@link module:font/fontfamily~FontFamily} – allows to change the font family by applying inline `<span>` elements with a `font-family` in the `style` attribute,
+* {@link module:font/fontsize~FontSize} – allows to control size by applying inline `<span>` elements that either have a CSS class or a `font-size` in the `style` attribute.
 
 ## Demo
 
 {@snippet features/font}
 
-## Configuring font family options
+## Configuring the font family
 
 It is possible to configure which font family options are supported by the editor. Use the {@link module:font/fontfamily~FontFamilyConfig#options `fontFamily.options`} configuration option to do so.
 
-Use the special keyword `'default'` to use the default `font-family` defined in the web page styles — it disables the font family feature.
+Use the special `'default'` keyword to use the default `font-family` defined in the web page styles (removes any custom font family).
 
 For example, the following editor supports only two font families besides the "default" one:
 
@@ -45,11 +41,11 @@ ClassicEditor
 
 {@snippet features/custom-font-family-options}
 
-## Configuring font size options
+## Configuring the font size
 
 It is possible to configure which font size options are supported by the editor. Use the {@link module:font/fontsize~FontSizeConfig#options `fontSize.options`} configuration option to do so.
 
-Use the special keyword `'normal'` to use the default font size defined in the web page styles — it disables the font-size feature.
+Use the special `'normal'` keyword to use the default font size defined in the web page styles (removes any custom size).
 
 The font size feature supports two ways of defining configuration: using  predefined (named) presets or simple numeric values.
 
@@ -67,11 +63,11 @@ Each size is represented in the view as a `<span>` element with the `text-*` cla
 <span class="text-tiny">...</span>
 ```
 
-The CSS definition for those CSS classes must be included:
-- on the web page's CSS stylesheet that the editor is included and 
-- on the web page's CSS stylesheet that renders edited content. 
+The CSS definition for the classes (presets) must be included:
+- in the web page's styles where the editor runs (backend),
+- in the web page's styles where the edited content is rendered (frontend)
 
-The examples defines below CSS:
+Here's an example of the font size CSS classes:
 
 ```css
 .text-tiny {
@@ -113,18 +109,18 @@ ClassicEditor
 
 {@snippet features/custom-font-size-named-options}
 
-### Configuration using numeric presets
+### Configuration using numerical values
 
-As an alternative, the font feature supports numeric values.
+The font feature also supports numerical values.
 
-Each size is represented in the view as a `<span>` element with the `font-size` style set in `px`.
+In this case, each size is represented in the view as a `<span>` element with the `font-size` style set in `px`.
 For example, `14` will be represented in the editor data as:
 
 ```html
 <span style="font-size: 14px">...</span>
 ```
 
-Here's an example of the editor that supports numeric font sizes (assuming that the `'normal'` size is defined by CSS as `15px`):
+Here's an example of the editor that supports numerical font sizes. Note that `'normal'` is controlled by the default styles of the web page:
 
 ```js
 ClassicEditor

+ 3 - 5
packages/ckeditor5-font/src/font.js

@@ -13,11 +13,9 @@ import FontFamily from './fontfamily';
 import FontSize from './fontsize';
 
 /**
- * A plugin that includes additional font features. It represents set of features that manipulates visual representation of text.
- *
- * This plugin enables:
- * * {@link module:font/fontsize~FontSize}
- * * {@link module:font/fontfamily~FontFamily} plugins.
+ * A plugin that enables (aggregates) a set of text styling features:
+ * * {@link module:font/fontsize~FontSize},
+ * * {@link module:font/fontfamily~FontFamily}.
  *
  * Read more about the feature in the {@glink api/font font package} page.
  *

+ 5 - 5
packages/ckeditor5-font/src/fontfamily.js

@@ -14,8 +14,8 @@ import FontFamilyUI from './fontfamily/fontfamilyui';
 /**
  * The font family plugin.
  *
- * It requires {@link module:font/fontfamily/fontfamilyediting~FontFamilyEditing} and
- * {@link module:font/fontfamily/fontfamilyui~FontFamilyUI} plugins.
+ * It enables {@link module:font/fontfamily/fontfamilyediting~FontFamilyEditing} and
+ * {@link module:font/fontfamily/fontfamilyui~FontFamilyUI} features in the editor.
  *
  * @extends module:core/plugin~Plugin
  */
@@ -36,14 +36,14 @@ export default class FontFamily extends Plugin {
 }
 
 /**
- * Font family option descriptor. Compatible with {@link module:engine/conversion/definition-based-converters~ConverterDefinition}.
+ * Font family option descriptor.
  *
  * @typedef {Object} module:font/fontfamily~FontFamilyOption
  *
  * @property {String} title The user-readable title of the option.
  * @property {String} model Attribute's unique value in the model.
- * @property {module:engine/view/viewelementdefinition~ViewElementDefinition} view View element configuration.
- * @property {Array.<module:engine/view/viewelementdefinition~ViewElementDefinition>} [upcastAlso] An array with all matched elements that
+ * @property {module:engine/view/elementdefinition~ElementDefinition} view View element configuration.
+ * @property {Array.<module:engine/view/elementdefinition~ElementDefinition>} [upcastAlso] An array with all matched elements that
  * view to model conversion should also accept.
  */
 

+ 4 - 2
packages/ckeditor5-font/src/fontfamily/fontfamilycommand.js

@@ -11,11 +11,13 @@ import FontCommand from '../fontcommand';
 
 /**
  * The font family command. It is used by the {@link module:font/fontfamily/fontfamilyediting~FontFamilyEditing}
- * to apply font family.
+ * to apply the font family.
  *
  *		editor.execute( 'fontFamily', { value: 'Arial' } );
  *
- * @extends module:core/command~Command
+ * **Note**: Executing the command without the value removes the attribute from the model.
+ *
+ * @extends module:font/fontcommand~FontCommand
  */
 export default class FontFamilyCommand extends FontCommand {
 	/**

+ 6 - 2
packages/ckeditor5-font/src/fontfamily/fontfamilyediting.js

@@ -16,8 +16,12 @@ import { normalizeOptions } from './utils';
 const FONT_FAMILY = 'fontFamily';
 
 /**
- * The font family editing feature. It introduces the `'fontFamily'` command and introduces `fontFamily` attribute in the model
- * which renders to the view as a `<span>` element with a `font-family` style attribute.
+ * The font family editing feature.
+ *
+ * It introduces the {@link module:font/fontfamily/fontfamilycommand~FontFamilyCommand command} and
+ * the `fontFamily` attribute in the {@link module:engine/model/model~Model model} which renders
+ * in the {@link module:engine/view/view view} as an inline span (`<span style="font-family: Arial">`),
+ * depending on the {@link module:font/fontfamily~FontFamilyConfig configuration}.
  *
  * @extends module:core/plugin~Plugin
  */

+ 5 - 5
packages/ckeditor5-font/src/fontsize.js

@@ -14,8 +14,8 @@ import FontSizeUI from './fontsize/fontsizeui';
 /**
  * The font size plugin.
  *
- * It requires {@link module:font/fontsize/fontsizeediting~FontSizeEditing} and
- * {@link module:font/fontsize/fontsizeui~FontSizeUI} plugins.
+ * It enables {@link module:font/fontsize/fontsizeediting~FontSizeEditing} and
+ * {@link module:font/fontsize/fontsizeui~FontSizeUI} features in the editor.
  *
  * @extends module:core/plugin~Plugin
  */
@@ -36,14 +36,14 @@ export default class FontSize extends Plugin {
 }
 
 /**
- * Font size option descriptor. Compatible with {@link module:engine/conversion/definition-based-converters~ConverterDefinition}.
+ * Font size option descriptor.
  *
  * @typedef {Object} module:font/fontsize~FontSizeOption
  *
  * @property {String} title The user-readable title of the option.
  * @property {String} model Attribute's unique value in the model.
- * @property {module:engine/view/viewelementdefinition~ViewElementDefinition} view View element configuration.
- * @property {Array.<module:engine/view/viewelementdefinition~ViewElementDefinition>} [upcastAlso] An array with all matched elements that
+ * @property {module:engine/view/elementdefinition~ElementDefinition} view View element configuration.
+ * @property {Array.<module:engine/view/elementdefinition~ElementDefinition>} [upcastAlso] An array with all matched elements that
  * view to model conversion should also accept.
  */
 

+ 4 - 2
packages/ckeditor5-font/src/fontsize/fontsizecommand.js

@@ -11,11 +11,13 @@ import FontCommand from '../fontcommand';
 
 /**
  * The font size command. It is used by the {@link module:font/fontsize/fontsizeediting~FontSizeEditing}
- * to apply font size.
+ * to apply the font size.
  *
  *		editor.execute( 'fontSize', { value: 'small' } );
  *
- * @extends module:core/command~Command
+ * **Note**: Executing the command without the value removes the attribute from the model.
+ *
+ * @extends module:font/fontcommand~FontCommand
  */
 export default class FontSizeCommand extends FontCommand {
 	/**

+ 9 - 2
packages/ckeditor5-font/src/fontsize/fontsizeediting.js

@@ -16,8 +16,15 @@ import { normalizeOptions } from './utils';
 const FONT_SIZE = 'fontSize';
 
 /**
- * The font size editing feature. It introduces the `'fontSize'` command and introduces `fontSize` attribute in the model which renders
- * to the view depending on configuration as a `<span>` element with either a `font-size` style attribute or a class attribute.
+ * The font size editing feature.
+ *
+ * It introduces the {@link module:font/fontsize/fontsizecommand~FontSizeCommand command} and the `fontSize`
+ * attribute in the {@link module:engine/model/model~Model model} which renders in the {@link module:engine/view/view view}
+ * as a `<span>` element with either:
+ * * a style attribute (`<span style="font-size:12px">...</span>`),
+ * * or a class attribute (`<span class="text-small">...</span>`)
+ *
+ * depending on the {@link module:font/fontsize~FontSizeConfig configuration}.
  *
  * @extends module:core/plugin~Plugin
  */