@ckeditor/ckeditor5-engine 36.0.1 → 37.0.0-alpha.1

package/src/view/stylesmap.js

@@ -14,32 +14,13 @@ import { get, isObject, merge, set, unset } from 'lodash-es';
 export default class StylesMap {
     /**
      * Creates Styles instance.
-     *
-     * @param {module:engine/view/stylesmap~StylesProcessor} styleProcessor
      */
     constructor(styleProcessor) {
-        /**
-         * Keeps an internal representation of styles map. Normalized styles are kept as object tree to allow unified modification and
-         * value access model using lodash's get, set, unset, etc methods.
-         *
-         * When no style processor rules are defined it acts as simple key-value storage.
-         *
-         * @private
-         * @type {Object}
-         */
         this._styles = {};
-        /**
-         * An instance of the {@link module:engine/view/stylesmap~StylesProcessor}.
-         *
-         * @private
-         * @member {module:engine/view/stylesmap~StylesProcessor}
-         */
         this._styleProcessor = styleProcessor;
     }
     /**
      * Returns true if style map has no styles set.
-     *
-     * @type {Boolean}
      */
     get isEmpty() {
         const entries = Object.entries(this._styles);
@@ -48,8 +29,6 @@ export default class StylesMap {
     }
     /**
      * Number of styles defined.
-     *
-     * @type {Number}
      */
     get size() {
         if (this.isEmpty) {
@@ -60,9 +39,9 @@ export default class StylesMap {
     /**
      * Set styles map to a new value.
      *
-     *		styles.setTo( 'border:1px solid blue;margin-top:1px;' );
-     *
-     * @param {String} inlineStyle
+     * ```ts
+     * styles.setTo( 'border:1px solid blue;margin-top:1px;' );
+     * ```
      */
     setTo(inlineStyle) {
         this.clear();
@@ -74,30 +53,33 @@ export default class StylesMap {
     /**
      * Checks if a given style is set.
      *
-     *		styles.setTo( 'margin-left:1px;' );
+     * ```ts
+     * styles.setTo( 'margin-left:1px;' );
      *
-     *		styles.has( 'margin-left' );    // -> true
-     *		styles.has( 'padding' );        // -> false
+     * styles.has( 'margin-left' );    // -> true
+     * styles.has( 'padding' );        // -> false
+     * ```
      *
      * **Note**: This check supports normalized style names.
      *
-     *		// Enable 'margin' shorthand processing:
-     *		editor.data.addStyleProcessorRules( addMarginRules );
+     * ```ts
+     * // Enable 'margin' shorthand processing:
+     * editor.data.addStyleProcessorRules( addMarginRules );
      *
-     *		styles.setTo( 'margin:2px;' );
+     * styles.setTo( 'margin:2px;' );
      *
-     *		styles.has( 'margin' );         // -> true
-     *		styles.has( 'margin-top' );     // -> true
-     *		styles.has( 'margin-left' );    // -> true
+     * styles.has( 'margin' );         // -> true
+     * styles.has( 'margin-top' );     // -> true
+     * styles.has( 'margin-left' );    // -> true
      *
-     *		styles.remove( 'margin-top' );
+     * styles.remove( 'margin-top' );
      *
-     *		styles.has( 'margin' );         // -> false
-     *		styles.has( 'margin-top' );     // -> false
-     *		styles.has( 'margin-left' );    // -> true
+     * styles.has( 'margin' );         // -> false
+     * styles.has( 'margin-top' );     // -> false
+     * styles.has( 'margin-left' );    // -> true
+     * ```
      *
-     * @param {String} name Style name.
-     * @returns {Boolean}
+     * @param name Style name.
      */
     has(name) {
         if (this.isEmpty) {
@@ -121,26 +103,30 @@ export default class StylesMap {
     /**
      * Removes given style.
      *
-     *		styles.setTo( 'background:#f00;margin-right:2px;' );
+     * ```ts
+     * styles.setTo( 'background:#f00;margin-right:2px;' );
      *
-     *		styles.remove( 'background' );
+     * styles.remove( 'background' );
      *
-     *		styles.toString();   // -> 'margin-right:2px;'
+     * styles.toString();   // -> 'margin-right:2px;'
+     * ```
      *
      * ***Note**:* This method uses {@link module:engine/controller/datacontroller~DataController#addStyleProcessorRules
      * enabled style processor rules} to normalize passed values.
      *
-     *		// Enable 'margin' shorthand processing:
-     *		editor.data.addStyleProcessorRules( addMarginRules );
+     * ```ts
+     * // Enable 'margin' shorthand processing:
+     * editor.data.addStyleProcessorRules( addMarginRules );
      *
-     *		styles.setTo( 'margin:1px' );
+     * styles.setTo( 'margin:1px' );
      *
-     *		styles.remove( 'margin-top' );
-     *		styles.remove( 'margin-right' );
+     * styles.remove( 'margin-top' );
+     * styles.remove( 'margin-right' );
      *
-     *		styles.toString(); // -> 'margin-bottom:1px;margin-left:1px;'
+     * styles.toString(); // -> 'margin-bottom:1px;margin-left:1px;'
+     * ```
      *
-     * @param {String} name Style name.
+     * @param name Style name.
      */
     remove(name) {
         const path = toPath(name);
@@ -151,27 +137,28 @@ export default class StylesMap {
     /**
      * Returns a normalized style object or a single value.
      *
-     *		// Enable 'margin' shorthand processing:
-     *		editor.data.addStyleProcessorRules( addMarginRules );
+     * ```ts
+     * // Enable 'margin' shorthand processing:
+     * editor.data.addStyleProcessorRules( addMarginRules );
      *
-     *		const styles = new Styles();
-     *		styles.setTo( 'margin:1px 2px 3em;' );
+     * const styles = new Styles();
+     * styles.setTo( 'margin:1px 2px 3em;' );
      *
-     *		styles.getNormalized( 'margin' );
-     *		// will log:
-     *		// {
-     *		//     top: '1px',
-     *		//     right: '2px',
-     *		//     bottom: '3em',
-     *		//     left: '2px'     // normalized value from margin shorthand
-     *		// }
+     * styles.getNormalized( 'margin' );
+     * // will log:
+     * // {
+     * //     top: '1px',
+     * //     right: '2px',
+     * //     bottom: '3em',
+     * //     left: '2px'     // normalized value from margin shorthand
+     * // }
      *
-     *		styles.getNormalized( 'margin-left' ); // -> '2px'
+     * styles.getNormalized( 'margin-left' ); // -> '2px'
+     * ```
      *
      * **Note**: This method will only return normalized styles if a style processor was defined.
      *
-     * @param {String} name Style name.
-     * @returns {Object|String|undefined}
+     * @param name Style name.
      */
     getNormalized(name) {
         return this._styleProcessor.getNormalized(name, this._styles);
@@ -179,24 +166,26 @@ export default class StylesMap {
     /**
      * Returns a normalized style string. Styles are sorted by name.
      *
-     *		styles.set( 'margin' , '1px' );
-     *		styles.set( 'background', '#f00' );
+     * ```ts
+     * styles.set( 'margin' , '1px' );
+     * styles.set( 'background', '#f00' );
      *
-     *		styles.toString(); // -> 'background:#f00;margin:1px;'
+     * styles.toString(); // -> 'background:#f00;margin:1px;'
+     * ```
      *
      * **Note**: This method supports normalized styles if defined.
      *
-     *		// Enable 'margin' shorthand processing:
-     *		editor.data.addStyleProcessorRules( addMarginRules );
-     *
-     *		styles.set( 'margin' , '1px' );
-     *		styles.set( 'background', '#f00' );
-     *		styles.remove( 'margin-top' );
-     *		styles.remove( 'margin-right' );
+     * ```ts
+     * // Enable 'margin' shorthand processing:
+     * editor.data.addStyleProcessorRules( addMarginRules );
      *
-     *		styles.toString(); // -> 'background:#f00;margin-bottom:1px;margin-left:1px;'
+     * styles.set( 'margin' , '1px' );
+     * styles.set( 'background', '#f00' );
+     * styles.remove( 'margin-top' );
+     * styles.remove( 'margin-right' );
      *
-     * @returns {String}
+     * styles.toString(); // -> 'background:#f00;margin-bottom:1px;margin-left:1px;'
+     * ```
      */
     toString() {
         if (this.isEmpty) {
@@ -210,53 +199,58 @@ export default class StylesMap {
     /**
      * Returns property as a value string or undefined if property is not set.
      *
-     *		// Enable 'margin' shorthand processing:
-     *		editor.data.addStyleProcessorRules( addMarginRules );
+     * ```ts
+     * // Enable 'margin' shorthand processing:
+     * editor.data.addStyleProcessorRules( addMarginRules );
      *
-     *		const styles = new Styles();
-     *		styles.setTo( 'margin:1px;' );
-     *		styles.set( 'margin-bottom', '3em' );
+     * const styles = new Styles();
+     * styles.setTo( 'margin:1px;' );
+     * styles.set( 'margin-bottom', '3em' );
      *
-     *		styles.getAsString( 'margin' ); // -> 'margin: 1px 1px 3em;'
+     * styles.getAsString( 'margin' ); // -> 'margin: 1px 1px 3em;'
+     * ```
      *
      * Note, however, that all sub-values must be set for the longhand property name to return a value:
      *
-     *		const styles = new Styles();
-     *		styles.setTo( 'margin:1px;' );
-     *		styles.remove( 'margin-bottom' );
+     * ```ts
+     * const styles = new Styles();
+     * styles.setTo( 'margin:1px;' );
+     * styles.remove( 'margin-bottom' );
      *
-     *		styles.getAsString( 'margin' ); // -> undefined
+     * styles.getAsString( 'margin' ); // -> undefined
+     * ```
      *
      * In the above scenario, it is not possible to return a `margin` value, so `undefined` is returned.
      * Instead, you should use:
      *
-     *		const styles = new Styles();
-     *		styles.setTo( 'margin:1px;' );
-     *		styles.remove( 'margin-bottom' );
+     * ```ts
+     * const styles = new Styles();
+     * styles.setTo( 'margin:1px;' );
+     * styles.remove( 'margin-bottom' );
      *
-     *		for ( const styleName of styles.getStyleNames() ) {
-     *			console.log( styleName, styles.getAsString( styleName ) );
-     *		}
-     *		// 'margin-top', '1px'
-     *		// 'margin-right', '1px'
-     *		// 'margin-left', '1px'
+     * for ( const styleName of styles.getStyleNames() ) {
+     * 	console.log( styleName, styles.getAsString( styleName ) );
+     * }
+     * // 'margin-top', '1px'
+     * // 'margin-right', '1px'
+     * // 'margin-left', '1px'
+     * ```
      *
      * In general, it is recommend to iterate over style names like in the example above. This way, you will always get all
      * the currently set style values. So, if all the 4 margin values would be set
      * the for-of loop above would yield only `'margin'`, `'1px'`:
      *
-     *		const styles = new Styles();
-     *		styles.setTo( 'margin:1px;' );
+     * ```ts
+     * const styles = new Styles();
+     * styles.setTo( 'margin:1px;' );
      *
-     *		for ( const styleName of styles.getStyleNames() ) {
-     *			console.log( styleName, styles.getAsString( styleName ) );
-     *		}
-     *		// 'margin', '1px'
+     * for ( const styleName of styles.getStyleNames() ) {
+     * 	console.log( styleName, styles.getAsString( styleName ) );
+     * }
+     * // 'margin', '1px'
+     * ```
      *
      * **Note**: To get a normalized version of a longhand property use the {@link #getNormalized `#getNormalized()`} method.
-     *
-     * @param {String} propertyName
-     * @returns {String|undefined}
      */
     getAsString(propertyName) {
         if (this.isEmpty) {
@@ -278,14 +272,17 @@ export default class StylesMap {
      *
      * When `expand` is set to true and there's a shorthand style property set, it will also return all equivalent styles:
      *
-     * 		stylesMap.setTo( 'margin: 1em' )
+     * ```ts
+     * stylesMap.setTo( 'margin: 1em' )
+     * ```
      *
      * will be expanded to:
      *
-     * 		[ 'margin', 'margin-top', 'margin-right', 'margin-bottom', 'margin-left' ]
+     * ```ts
+     * [ 'margin', 'margin-top', 'margin-right', 'margin-bottom', 'margin-left' ]
+     * ```
      *
-     * @param {Boolean} [expand=false] Expand shorthand style properties and all return equivalent style representations.
-     * @returns {Array.<String>}
+     * @param expand Expand shorthand style properties and all return equivalent style representations.
      */
     getStyleNames(expand = false) {
         if (this.isEmpty) {
@@ -305,9 +302,6 @@ export default class StylesMap {
     }
     /**
      * Returns normalized styles entries for further processing.
-     *
-     * @private
-     * @returns {Array.<module:engine/view/stylesmap~PropertyDescriptor>}
      */
     _getStylesEntries() {
         const parsed = [];
@@ -319,9 +313,6 @@ export default class StylesMap {
     }
     /**
      * Removes empty objects upon removing an entry from internal object.
-     *
-     * @param {String} path
-     * @private
      */
     _cleanEmptyObjectsOnPath(path) {
         const pathParts = path.split('.');
@@ -347,7 +338,7 @@ export class StylesProcessor {
     /**
      * Creates StylesProcessor instance.
      *
-     * @private
+     * @internal
      */
     constructor() {
         this._normalizers = new Map();
@@ -358,17 +349,19 @@ export class StylesProcessor {
     /**
      * Parse style string value to a normalized object and appends it to styles object.
      *
-     *		const styles = {};
+     * ```ts
+     * const styles = {};
      *
-     *		stylesProcessor.toNormalizedForm( 'margin', '1px', styles );
+     * stylesProcessor.toNormalizedForm( 'margin', '1px', styles );
      *
-     *		// styles will consist: { margin: { top: '1px', right: '1px', bottom: '1px', left: '1px; } }
+     * // styles will consist: { margin: { top: '1px', right: '1px', bottom: '1px', left: '1px; } }
+     * ```
      *
      * **Note**: To define normalizer callbacks use {@link #setNormalizer}.
      *
-     * @param {String} name Name of style property.
-     * @param {String} propertyValue Value of style property.
-     * @param {Object} styles Object holding normalized styles.
+     * @param name Name of style property.
+     * @param propertyValue Value of style property.
+     * @param styles Object holding normalized styles.
      */
     toNormalizedForm(name, propertyValue, styles) {
         if (isObject(propertyValue)) {
@@ -386,22 +379,24 @@ export class StylesProcessor {
     }
     /**
      * Returns a normalized version of a style property.
-     *		const styles = {
-     *			margin: { top: '1px', right: '1px', bottom: '1px', left: '1px; },
-     *			background: { color: '#f00' }
-     *		};
      *
-     *		stylesProcessor.getNormalized( 'background' );
-     *		// will return: { color: '#f00' }
+     * ```ts
+     * const styles = {
+     * 	margin: { top: '1px', right: '1px', bottom: '1px', left: '1px; },
+     * 	background: { color: '#f00' }
+     * };
+     *
+     * stylesProcessor.getNormalized( 'background' );
+     * // will return: { color: '#f00' }
      *
-     *		stylesProcessor.getNormalized( 'margin-top' );
-     *		// will return: '1px'
+     * stylesProcessor.getNormalized( 'margin-top' );
+     * // will return: '1px'
+     * ```
      *
      * **Note**: In some cases extracting single value requires defining an extractor callback {@link #setExtractor}.
      *
-     * @param {String} name Name of style property.
-     * @param {Object} styles Object holding normalized styles.
-     * @returns {*}
+     * @param name Name of style property.
+     * @param styles Object holding normalized styles.
      */
     getNormalized(name, styles) {
         if (!name) {
@@ -428,30 +423,34 @@ export class StylesProcessor {
      *
      * For default margin reducer, the below code:
      *
-     *		stylesProcessor.getReducedForm( 'margin', {
-     *			margin: { top: '1px', right: '1px', bottom: '2px', left: '1px; }
-     *		} );
+     * ```ts
+     * stylesProcessor.getReducedForm( 'margin', {
+     * 	margin: { top: '1px', right: '1px', bottom: '2px', left: '1px; }
+     * } );
+     * ```
      *
      * will return:
      *
-     *		[
-     *			[ 'margin', '1px 1px 2px' ]
-     *		]
+     * ```ts
+     * [
+     * 	[ 'margin', '1px 1px 2px' ]
+     * ]
+     * ```
      *
      * because it might be represented as a shorthand 'margin' value. However if one of margin long hand values is missing it should return:
      *
-     *		[
-     *			[ 'margin-top', '1px' ],
-     *			[ 'margin-right', '1px' ],
-     *			[ 'margin-bottom', '2px' ]
-     *			// the 'left' value is missing - cannot use 'margin' shorthand.
-     *		]
+     * ```ts
+     * [
+     * 	[ 'margin-top', '1px' ],
+     * 	[ 'margin-right', '1px' ],
+     * 	[ 'margin-bottom', '2px' ]
+     * 	// the 'left' value is missing - cannot use 'margin' shorthand.
+     * ]
+     * ```
      *
      * **Note**: To define reducer callbacks use {@link #setReducer}.
      *
-     * @param {String} name Name of style property.
-     * @param {Object} styles Object holding normalized styles.
-     * @returns {Array.<module:engine/view/stylesmap~PropertyDescriptor>}
+     * @param name Name of style property.
      */
     getReducedForm(name, styles) {
         const normalizedValue = this.getNormalized(name, styles);
@@ -468,8 +467,7 @@ export class StylesProcessor {
     /**
      * Return all style properties. Also expand shorthand properties (e.g. `margin`, `background`) if respective extractor is available.
      *
-     * @param {Object} styles Object holding normalized styles.
-     * @returns {Array.<String>}
+     * @param styles Object holding normalized styles.
      */
     getStyleNames(styles) {
         // Find all extractable styles that have a value.
@@ -491,17 +489,16 @@ export class StylesProcessor {
     /**
      * Returns related style names.
      *
-     *		stylesProcessor.getRelatedStyles( 'margin' );
-     *		// will return: [ 'margin-top', 'margin-right', 'margin-bottom', 'margin-left' ];
+     * ```ts
+     * stylesProcessor.getRelatedStyles( 'margin' );
+     * // will return: [ 'margin-top', 'margin-right', 'margin-bottom', 'margin-left' ];
      *
-     *		stylesProcessor.getRelatedStyles( 'margin-top' );
-     *		// will return: [ 'margin' ];
+     * stylesProcessor.getRelatedStyles( 'margin-top' );
+     * // will return: [ 'margin' ];
+     * ```
      *
      * **Note**: To define new style relations load an existing style processor or use
      * {@link module:engine/view/stylesmap~StylesProcessor#setStyleRelation `StylesProcessor.setStyleRelation()`}.
-     *
-     * @param {String} name
-     * @returns {Array.<String>}
      */
     getRelatedStyles(name) {
         return this._consumables.get(name) || [];
@@ -523,39 +520,42 @@ export class StylesProcessor {
      *
      * A normalizer should parse various margin notations as a single object:
      *
-     *		const styles = {
-     *			margin: {
-     *				top: '1px',
-     *				right: '2em',
-     *				bottom: '1px',
-     *				left: '2em'
-     *			}
-     *		};
+     * ```ts
+     * const styles = {
+     * 	margin: {
+     * 		top: '1px',
+     * 		right: '2em',
+     * 		bottom: '1px',
+     * 		left: '2em'
+     * 	}
+     * };
+     * ```
      *
      * Thus a normalizer for 'margin' style should return an object defining style path and value to store:
      *
-     *		const returnValue = {
-     *			path: 'margin',
-     *			value: {
-     *				top: '1px',
-     *				right: '2em',
-     *				bottom: '1px',
-     *				left: '2em'
-     *			}
-     *		};
+     * ```ts
+     * const returnValue = {
+     * 	path: 'margin',
+     * 	value: {
+     * 		top: '1px',
+     * 		right: '2em',
+     * 		bottom: '1px',
+     * 		left: '2em'
+     * 	}
+     * };
+     * ```
      *
      * Additionally to fully support all margin notations there should be also defined 4 normalizers for longhand margin notations. Below
      * is an example for 'margin-top' style property normalizer:
      *
-     *		stylesProcessor.setNormalizer( 'margin-top', valueString => {
-     *			return {
-     *				path: 'margin.top',
-     *				value: valueString
-     *			}
-     *		} );
-     *
-     * @param {String} name
-     * @param {Function} callback
+     * ```ts
+     * stylesProcessor.setNormalizer( 'margin-top', valueString => {
+     * 	return {
+     * 		path: 'margin.top',
+     * 		value: valueString
+     * 	}
+     * } );
+     * ```
      */
     setNormalizer(name, callback) {
         this._normalizers.set(name, callback);
@@ -565,39 +565,44 @@ export class StylesProcessor {
      *
      * Most normalized style values are stored as one level objects. It is assumed that `'margin-top'` style will be stored as:
      *
-     *		const styles = {
-     *			margin: {
-     *				top: 'value'
-     *			}
-     *		}
+     * ```ts
+     * const styles = {
+     * 	margin: {
+     * 		top: 'value'
+     * 	}
+     * }
+     * ```
      *
      * However, some styles can have conflicting notations and thus it might be harder to extract a style value from shorthand. For instance
      * the 'border-top-style' can be defined using `'border-top:solid'`, `'border-style:solid none none none'` or by `'border:solid'`
      * shorthands. The default border styles processors stores styles as:
      *
-     *		const styles = {
-     *			border: {
-     *				style: {
-     *					top: 'solid'
-     *				}
-     *			}
-     *		}
+     * ```ts
+     * const styles = {
+     * 	border: {
+     * 		style: {
+     * 			top: 'solid'
+     * 		}
+     * 	}
+     * }
+     * ```
      *
      * as it is better to modify border style independently from other values. On the other part the output of the border might be
      * desired as `border-top`, `border-left`, etc notation.
      *
-     * In the above example a reducer should return a side border value that combines style, color and width:
+     * In the above example an extractor should return a side border value that combines style, color and width:
      *
-     *		styleProcessor.setExtractor( 'border-top', styles => {
-     *			return {
-     *				color: styles.border.color.top,
-     *				style: styles.border.style.top,
-     *				width: styles.border.width.top
-     *			}
-     *		} );
+     * ```ts
+     * styleProcessor.setExtractor( 'border-top', styles => {
+     * 	return {
+     * 		color: styles.border.color.top,
+     * 		style: styles.border.style.top,
+     * 		width: styles.border.width.top
+     * 	}
+     * } );
+     * ```
      *
-     * @param {String} name
-     * @param {Function|String} callbackOrPath Callback that return a requested value or path string for single values.
+     * @param callbackOrPath Callback that return a requested value or path string for single values.
      */
     setExtractor(name, callbackOrPath) {
         this._extractors.set(name, callbackOrPath);
@@ -611,29 +616,32 @@ export class StylesProcessor {
      * For shorthand styles a reducer should return minimal style notation either by returning single name-value tuple or multiple tuples
      * if a shorthand cannot be used. For instance for a margin shorthand a reducer might return:
      *
-     *		const marginShortHandTuple = [
-     *			[ 'margin', '1px 1px 2px' ]
-     *		];
+     * ```ts
+     * const marginShortHandTuple = [
+     * 	[ 'margin', '1px 1px 2px' ]
+     * ];
+     * ```
      *
      * or a longhand tuples for defined values:
      *
-     *		// Considering margin.bottom and margin.left are undefined.
-     *		const marginLonghandsTuples = [
-     *			[ 'margin-top', '1px' ],
-     *			[ 'margin-right', '1px' ]
-     *		];
+     * ```ts
+     * // Considering margin.bottom and margin.left are undefined.
+     * const marginLonghandsTuples = [
+     * 	[ 'margin-top', '1px' ],
+     * 	[ 'margin-right', '1px' ]
+     * ];
+     * ```
      *
      * A reducer obtains a normalized style value:
      *
-     *		// Simplified reducer that always outputs 4 values which are always present:
-     *		stylesProcessor.setReducer( 'margin', margin => {
-     *			return [
-     *				[ 'margin', `${ margin.top } ${ margin.right } ${ margin.bottom } ${ margin.left }` ]
-     *			]
-     *		} );
-     *
-     * @param {String} name
-     * @param {Function} callback
+     * ```ts
+     * // Simplified reducer that always outputs 4 values which are always present:
+     * stylesProcessor.setReducer( 'margin', margin => {
+     * 	return [
+     * 		[ 'margin', `${ margin.top } ${ margin.right } ${ margin.bottom } ${ margin.left }` ]
+     * 	]
+     * } );
+     * ```
      */
     setReducer(name, callback) {
         this._reducers.set(name, callback);
@@ -641,12 +649,14 @@ export class StylesProcessor {
     /**
      * Defines a style shorthand relation to other style notations.
      *
-     *		stylesProcessor.setStyleRelation( 'margin', [
-     *			'margin-top',
-     *			'margin-right',
-     *			'margin-bottom',
-     *			'margin-left'
-     *		] );
+     * ```ts
+     * stylesProcessor.setStyleRelation( 'margin', [
+     * 	'margin-top',
+     * 	'margin-right',
+     * 	'margin-bottom',
+     * 	'margin-left'
+     * ] );
+     * ```
      *
      * This enables expanding of style names for shorthands. For instance, if defined,
      * {@link module:engine/conversion/viewconsumable~ViewConsumable view consumable} items are automatically created
@@ -656,9 +666,6 @@ export class StylesProcessor {
      * fine since the view consumable will contain a consumable `margin-left` item (thanks to the relation) and
      * `element.getStyle( 'margin-left' )` will work as well assuming that the style processor was correctly configured.
      * However, once `margin-left` is consumed, `margin` will not be consumable anymore.
-     *
-     * @param {String} shorthandName
-     * @param {Array.<String>} styleNames
      */
     setStyleRelation(shorthandName, styleNames) {
         this._mapStyleNames(shorthandName, styleNames);
@@ -668,10 +675,6 @@ export class StylesProcessor {
     }
     /**
      * Set two-way binding of style names.
-     *
-     * @param {String} name
-     * @param {Array.<String>} styleNames
-     * @private
      */
     _mapStyleNames(name, styleNames) {
         if (!this._consumables.has(name)) {
@@ -680,10 +683,12 @@ export class StylesProcessor {
         this._consumables.get(name).push(...styleNames);
     }
 }
-// Parses inline styles and puts property - value pairs into styles map.
-//
-// @param {String} stylesString Styles to parse.
-// @returns {Map.<String, String>} stylesMap Map of parsed properties and values.
+/**
+ * Parses inline styles and puts property - value pairs into styles map.
+ *
+ * @param stylesString Styles to parse.
+ * @returns Map of parsed properties and values.
+ */
 function parseInlineStyles(stylesString) {
     // `null` if no quote was found in input string or last found quote was a closing quote. See below.
     let quoteType = null;
@@ -743,15 +748,15 @@ function parseInlineStyles(stylesString) {
     }
     return stylesMap;
 }
-// Return lodash compatible path from style name.
+/**
+ * Return lodash compatible path from style name.
+ */
 function toPath(name) {
     return name.replace('-', '.');
 }
-// Appends style definition to the styles object.
-//
-// @param {String} nameOrPath
-// @param {String|Object} valueOrObject
-// @private
+/**
+ * Appends style definition to the styles object.
+ */
 function appendStyleValue(stylesObject, nameOrPath, valueOrObject) {
     let valueToSet = valueOrObject;
     if (isObject(valueOrObject)) {