Docs: Review Font documentation.

src/fontcommand.js

@@ -16,9 +16,9 @@ import Command from '@ckeditor/ckeditor5-core/src/command';
  */
 export default class FontCommand extends Command {
 	/**
-	 * Creates a new `FontCommand` instance.
+	 * Creates an instance of the command.
 	 *
-	 * @param {module:core/editor/editor~Editor} editor Editor on which this command will be used.
+	 * @param {module:core/editor/editor~Editor} editor Editor instance.
 	 * @param {String} attribute Name of an model attribute on which this command operates.
 	 */
 	constructor( editor, attribute ) {

src/fontfamily/fontfamilycommand.js

@@ -17,9 +17,9 @@ import FontCommand from '../fontcommand';
  */
 export default class FontFamilyCommand extends FontCommand {
 	/**
-	 * Creates a new `FontFamilyCommand` instance.
+	 * Creates an instance of the command.
 	 *
-	 * @param {module:core/editor/editor~Editor} editor Editor on which this command will be used.
+	 * @param {module:core/editor/editor~Editor} editor Editor instance.
 	 */
 	constructor( editor ) {
 		super( editor, 'fontFamily' );

src/fontfamily/fontfamilyediting.js

@@ -28,6 +28,7 @@ export default class FontFamilyEditing extends Plugin {
 	constructor( editor ) {
 		super( editor );
 
+		// Define default configuration using font families shortcuts.
 		editor.config.define( 'fontFamily', {
 			options: [
 				'default',
@@ -70,17 +71,17 @@ export default class FontFamilyEditing extends Plugin {
 }
 
 /**
- * Font family option. Compatible with {@link module:engine/conversion/definition-based-converters~ConverterDefinition}.
+ * Font family option descriptor. Compatible with {@link module:engine/conversion/definition-based-converters~ConverterDefinition}.
  *
  * @typedef {Object} module:font/fontfamily/fontfamilyediting~FontFamilyOption
  *
- * @property {String} model The `fontFamily` attribute value in the model.
- * @property {module:engine/view/viewelementdefinition~ViewElementDefinition} view The view representation for that option.
  * @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>} [acceptAlso] An array with all matched elements that
+ * view to model conversion should also accept.
  * @property {String} [uiStyle] The style which will be added to the dropdown item representing this option.
  * Defaults to `view.style[ 'font-family' ]`.
- * @property {Array.<module:engine/view/viewelementdefinition~ViewElementDefinition>} acceptAlso An array with all matched elements that
- * view to model conversion should also accept.
  */
 
 /**
@@ -127,11 +128,22 @@ export default class FontFamilyEditing extends Plugin {
  *			]
  *		};
  *
- * which configures 8 font family options and a default option that will remove font family to text default setting (defaulting to content
- * CSS styles).
+ * which configures 8 font family options. Each option consist one or more font-family names separated with coma. The first font name is
+ * used as dropdown item description in UI. The family names that consist spaces should not have quotes (as opposed to CSS standard).
+ * Appropriate quotes will be added in the view. For example, for the "Lucida Sans Unicode" the editor will render:
+ *
+ * 		<span style="font-family:'Lucida Sans Unicode','Lucida Grande',sans-serif">...</span>
+ *
+ * The "default" option is used to remove fontFamily from selection. In such case the text will
+ * be represented in view using default content CSS font-family.
+
+ * To use defined font families from {@link module:core/commandcollection~CommandCollection} use `fontFamily` command and pass desired
+ * font family as a value.
+ * For example, the below code will apply `fontFamily` attribute with `tiny` value to the current selection:
+ *
+ *		editor.execute( 'fontFamily', { value: 'tiny' } );
  *
- * TODO: what 'default' does.
- * TODO: how those string are translated to configuration
+ * Executing `fontFamily` command without value will remove `fontFamily` attribute from the current selection.
  *
  * @member {Array.<String|module:font/fontfamily/fontfamilyediting~FontFamilyOption>}
  *  module:font/fontfamily/fontfamilyediting~FontFamilyConfig#options

src/fontfamily/fontfamilyui.js

@@ -81,15 +81,15 @@ export default class FontFamilyUI extends Plugin {
 	}
 
 	/**
-	 * Returns TODO options as defined in `config.heading.options` but processed to consider
-	 * editor localization, i.e. to display {@link module:heading/heading~HeadingOption}
+	 * Returns options as defined in `config.fontFamily.options` but processed to consider
+	 * editor localization, i.e. to display {@link module:font/fontfamily/fontfamilyediting~FontFamilyOption}
 	 * in the correct language.
 	 *
 	 * Note: The reason behind this method is that there's no way to use {@link module:utils/locale~Locale#t}
 	 * when the user config is defined because the editor does not exist yet.
 	 *
 	 * @private
-	 * @returns {Array.<module:heading/heading~HeadingOption>}.
+	 * @returns {Array.<module:font/fontfamily/fontfamilyediting~FontFamilyOption>}.
 	 */
 	_getLocalizedOptions() {
 		const editor = this.editor;

src/fontfamily/utils.js

@@ -4,65 +4,65 @@
  */
 
 /**
- * @module font/fontfamily/fontfamilyediting
+ * @module font/fontfamily/utils
  */
 
 /**
  * Returns {@link module:font/fontfamily/fontfamilyediting~FontFamilyConfig#options} array with options normalized in the
- * {@link module:font/fontfamily/fontfamilyediting~FontFamilyOption} format, translated
- * `title` for each style.
+ * {@link module:font/fontfamily/fontfamilyediting~FontFamilyOption} format.
  *
+ * @param {Array.<String|Object>} configuredOptions An array of options taken from configuration.
  * @returns {Array.<module:font/fontfamily/fontfamilyediting~FontFamilyOption>}
  */
 export function normalizeOptions( configuredOptions ) {
-	const options = [];
-	for ( const item of configuredOptions ) {
-		const itemDefinition = getItemDefinition( item );
-
-		// Set only valid definitions.
-		if ( itemDefinition ) {
-			options.push( itemDefinition );
-		}
-	}
-
-	return options;
+	// Convert options to objects.
+	return configuredOptions
+		.map( getOptionDefinition )
+		// Filter out undefined values that `getOptionDefinition` might return.
+		.filter( option => !!option );
 }
 
-// Returns item definition from preset
-function getItemDefinition( item ) {
-	// Probably it is full item definition so return it.
-	if ( typeof item === 'object' ) {
-		return item;
+// Returns an option definition either created from string shortcut.
+// If object is passed then this method will return it without alternating it. Returns undefined for item than cannot be parsed.
+//
+// @param {String|Object} option
+// @returns {undefined|module:font/fontfamily/fontfamilyediting~FontFamilyOption}
+function getOptionDefinition( option ) {
+	// Treat any object as full item definition provided by user in configuration.
+	if ( typeof option === 'object' ) {
+		return option;
 	}
 
 	// Handle 'default' string as a special case. It will be used to remove the fontFamily attribute.
-	if ( item === 'default' ) {
+	if ( option === 'default' ) {
 		return {
 			title: 'Default',
 			model: undefined
 		};
 	}
 
 	// Ignore values that we cannot parse to a definition.
-	if ( typeof item !== 'string' ) {
+	if ( typeof option !== 'string' ) {
 		return;
 	}
 
-	return generateFontPreset( item );
+	// Return font family definition from font string.
+	return generateFontPreset( option );
 }
 
 // Creates a predefined preset for pixel size. It deconstructs font-family like string into full configuration option.
 // A font definition is passed as coma delimited set of font family names. Font names might be quoted.
 //
 // @param {String} A font definition form configuration.
 function generateFontPreset( fontDefinition ) {
-	// Remove quotes from font names - will be normalized later.
+	// Remove quotes from font names. They will be normalized later.
 	const fontNames = fontDefinition.replace( /"|'/g, '' ).split( ',' );
 
 	// The first matched font name will be used as dropdown list item title and as model value
 	const firstFontName = fontNames[ 0 ];
 
-	const cssFontNames = fontNames.map( normalizeFontName );
+	// CSS-compatible font names.
+	const cssFontNames = fontNames.map( normalizeFontNameForCSS );
 
 	// TODO: Maybe we can come with something better here?
 	// TODO: Also document this behavior in engine as it uses matcher~Pattern not ViewElementDefinition.
@@ -98,11 +98,11 @@ function generateFontPreset( fontDefinition ) {
 	};
 }
 
-// Normalizes font name for the view style attribute.
+// Normalizes font name for the style attribute. It adds braces (') if font name contains spaces.
 //
 // @param {String} fontName
 // @returns {String}
-function normalizeFontName( fontName ) {
+function normalizeFontNameForCSS( fontName ) {
 	fontName = fontName.trim();
 
 	// Compound font names should be quoted.

src/fontsize/fontsizecommand.js

@@ -17,9 +17,9 @@ import FontCommand from '../fontcommand';
  */
 export default class FontSizeCommand extends FontCommand {
 	/**
-	 * Creates a new `FontSizeCommand` instance.
+	 * Creates an instance of the command.
 	 *
-	 * @param {module:core/editor/editor~Editor} editor Editor on which this command will be used.
+	 * @param {module:core/editor/editor~Editor} editor Editor instance.
 	 */
 	constructor( editor ) {
 		super( editor, 'fontSize' );

src/fontsize/fontsizeediting.js

@@ -28,7 +28,7 @@ export default class FontSizeEditing extends Plugin {
 	constructor( editor ) {
 		super( editor );
 
-		// Define default configuration using named presets
+		// Define default configuration using named presets.
 		editor.config.define( 'fontSize', {
 			options: [
 				'tiny',
@@ -70,17 +70,20 @@ export default class FontSizeEditing extends Plugin {
 }
 
 /**
- * Font size option descriptor.
+ * Font size option descriptor. Compatible with {@link module:engine/conversion/definition-based-converters~ConverterDefinition}.
  *
  * @typedef {Object} module:font/fontsize/fontsizeediting~FontSizeOption
  *
- * @property {String} title TODO me
- * @property {String} model TODO me
+ * @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>} [acceptAlso] An array with all matched elements that
+ * view to model conversion should also accept.
  */
 
 /**
- * The configuration of the heading feature. Introduced by the {@link module:font/fontsize/fontsizeediting~FontSizeEditing} feature.
+ * The configuration of the font size feature.
+ * Introduced by the {@link module:font/fontsize/fontsizeediting~FontSizeEditing} feature.
  *
  * Read more in {@link module:font/fontsize/fontsizeediting~FontSizeConfig}.
  *
@@ -91,24 +94,55 @@ export default class FontSizeEditing extends Plugin {
  * The configuration of the font size feature.
  * The option is used by the {@link module:font/fontsize/fontsizeediting~FontSizeEditing} feature.
  *
- *        ClassicEditor
- *            .create( {
+ * 		ClassicEditor
+ * 			.create( {
  * 				fontSize: ... // Font size feature config.
  *			} )
- *            .then( ... )
- *            .catch( ... );
+ * 			.then( ... )
+ * 			.catch( ... );
  *
  * See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
  *
  * @interface module:font/fontsize/fontsizeediting~FontSizeConfig
  */
 
 /**
- * Available font size options. Defined either as array of strings.
+ * Available font size options. Defined either using predefined presets, numeric pixel values
+ * or {@link module:font/fontsize/fontsizeediting~FontSizeOption}.
+ *
+ * The default value is:
+ *
+ *		const fontSizeConfig = {
+ *			options: [
+ *				'tiny',
+ * 				'small',
+ * 				'normal',
+ * 				'big',
+ * 				'huge'
+ *			]
+ *		};
+ *
+ * It defines 4 sizes: "tiny", "small", "big" and "huge". Those values will be rendered as `span` elements in view. The "normal" defines
+ * text without a `fontSize` attribute set.
+ *
+ * Each rendered span in the view will have class attribute set corresponding to size name.
+ * For instance for "small" size the view will render:
+ *
+ * 		<span class="text-small">...</span>
+ *
+ * As an alternative the font size might be defined using numeric values (either as Number or as String):
+ *
+ * 		const fontSizeConfig = {
+ * 			options: [ 9, 10, 11, 12, 13, 14, 15 ]
+ * 		};
+ *
+ * To use defined font sizes from {@link module:core/commandcollection~CommandCollection} use `fontSize` command and pass desired
+ * font size as a value.
+ * For example, the below code will apply `fontSize` attribute with `tiny` value to the current selection:
+ *
+ *		editor.execute( 'fontSize', { value: 'tiny' } );
  *
- * The default value is
- * TODO code
- * which configures
+ * Executing `fontSize` command without value will remove `fontSize` attribute from the current selection.
  *
  * @member {Array.<String|Number|module:font/fontsize/fontsizeediting~FontSizeOption>}
  *  module:font/fontsize/fontsizeediting~FontSizeConfig#options

src/fontsize/fontsizeui.js

@@ -57,7 +57,6 @@ export default class FontSizeUI extends Plugin {
 		editor.ui.componentFactory.add( 'fontSize', locale => {
 			const dropdown = createListDropdown( dropdownModel, locale );
 
-			// TODO check if needed
 			dropdown.extendTemplate( {
 				attributes: {
 					class: [
@@ -77,15 +76,15 @@ export default class FontSizeUI extends Plugin {
 	}
 
 	/**
-	 * Returns heading options as defined in `config.heading.options` but processed to consider
-	 * editor localization, i.e. to display {@link module:heading/heading~HeadingOption}
+	 * Returns options as defined in `config.fontSize.options` but processed to consider
+	 * editor localization, i.e. to display {@link module:font/fontsize/fontsizeediting~FontSizeOption}
 	 * in the correct language.
 	 *
 	 * Note: The reason behind this method is that there's no way to use {@link module:utils/locale~Locale#t}
 	 * when the user config is defined because the editor does not exist yet.
 	 *
 	 * @private
-	 * @returns {Array.<module:heading/heading~HeadingOption>}.
+	 * @returns {Array.<module:font/fontsize/fontsizeediting~FontSizeOption>}.
 	 */
 	_getLocalizedOptions() {
 		const editor = this.editor;
@@ -104,7 +103,7 @@ export default class FontSizeUI extends Plugin {
 			const title = localizedTitles[ option.title ];
 
 			if ( title && title != option.title ) {
-				// Clone the option to avoid altering the original `config.heading.options`.
+				// Clone the option to avoid altering the original `config.fontSize.options`.
 				option = Object.assign( {}, option, { title } );
 			}