fix(jsdoc): pr fix

src/core/root.ts

@@ -2,19 +2,27 @@ import {ObserverCallback} from '@exadel/esl';
 import {ESLBaseElement} from '@exadel/esl/modules/esl-base-element/core';
 import {UIPStateModel} from './state-model';
 
-/** Container element for {@link UIPPlugin} components. */
+/**
+ * UI Playground root custom element definition,
+ * container element for {@link UIPPlugin} components.
+ * Define the bounds of UI Playground instance.
+ * Share the {@link UIPStateModel} instance between {@link UIPPlugin}-s.
+ */
 export class UIPRoot extends ESLBaseElement {
   public static is = 'uip-root';
   private _model = new UIPStateModel();
 
+  /** {@link UIPStateModel} instance to store UI Playground state. */
   public get model(): UIPStateModel {
     return this._model;
   }
 
+  /** Alias for {@link this.model.addListener}. */
   public addStateListener(listener: ObserverCallback) {
     this._model.addListener(listener);
   }
 
+  /** Alias for {@link this.model.removeListener}. */
   public removeStateListener(listener: ObserverCallback) {
     this._model.removeListener(listener);
   }

src/core/state-model.ts

@@ -1,14 +1,14 @@
 import {Observable} from '@exadel/esl/modules/esl-utils/abstract/observable';
 import {UIPPlugin} from './plugin';
 
-/** Type for function which changes attribute's current value. */
+/** Type for function to change attribute's current value. */
 export type TransformSignature = (current: string | null) => string | boolean | null;
 
-/** Config used for changing attribute's value. */
+/** Config for changing attribute's value. */
 export type ChangeAttrConfig = {
-  /** Target whose {@link attribute} is changed. */
+  /** CSS query to find target elements. */
   target: string,
-  /** Attribute that is changed. */
+  /** Attribute to change. */
   attribute: string,
   /** Changes initiator. */
   modifier: UIPPlugin
@@ -17,24 +17,26 @@ export type ChangeAttrConfig = {
   value: string | boolean
 } | {
   /**
-   * Function which transforms current
-   * {@link attribute} value to the new one.
+   * Function to transform(update)
+   * {@link attribute} value.
    */
   transform: TransformSignature
 });
 
 /**
- * State manager class which contains current markup
- * and provides methods for changing it.
+ * State holder class to store current UIP markup state.
+ * Provides methods to modify the state.
+ * @extends Observable
  */
 export class UIPStateModel extends Observable {
   private _html = new DOMParser().parseFromString('', 'text/html').body;
   /** Last {@link UIPPlugin} element which changed markup. */
   private _lastModifier: UIPPlugin;
 
   /**
-   * Update current markup.
-   * Triggers [onRootStateChange]{@link UIPPlugin#_onRootStateChange}.
+   * Set current markup state to the passed one.
+   * @param markup - new state
+   * @param modifier - plugin, that initiate the change
    */
   public setHtml(markup: string, modifier: UIPPlugin) {
     const root = new DOMParser().parseFromString(markup, 'text/html').body;
@@ -54,7 +56,12 @@ export class UIPStateModel extends Observable {
     return this._lastModifier;
   }
 
-  /** Get attributes values from targets. */
+  /**
+   * Get attribute values for the matched set of elements.
+   * @param target - CSS sector to define target elements
+   * @param attr - attribute name
+   * @returns array of matched elements attribute value (uses the element placement order)
+   */
   public getAttribute(target: string, attr: string): (string | null)[] {
     return Array.from(this._html.querySelectorAll(target)).map(el => el.getAttribute(attr));
   }
@@ -70,7 +77,6 @@ export class UIPStateModel extends Observable {
     this.fire();
   }
 
-  /** Transform attributes values. */
   protected static setAttribute(elements: Element[], attr: string, transform: TransformSignature | string | boolean) {
     elements.forEach(el => {
       const transformed = typeof transform === 'function' ? transform(el.getAttribute(attr)) : transform;

src/editor/editor.ts

@@ -10,29 +10,24 @@ import {jsonAttr} from '@exadel/esl/modules/esl-base-element/core';
 
 import {UIPPlugin} from '../core/plugin';
 
-/** Config interface for customizing editor's behaviour. */
+/** Config interface to define inner ACE editor settings. */
 interface EditorConfig {
   /** Editor's appearance theme. */
   theme: string;
-  /**
-   * Text mode which is used
-   * inside the editor.
-   */
-  mode: string;
   /** Position of the vertical line for wrapping. */
   printMarginColumn: number;
   /** Limit of characters before wrapping. */
   wrap: number;
 }
 
 /**
- * Code editor for changing current markup. Allows user to manually configure
- * the component inside {@link UIPPreview}.
- * @see {@link UIPPlugin}
+ * Editor UIPPlugin custom element definition.
+ * Uses ACE UI code editor to provide an ability to modify UIP state markup.
+ * @extends UIPPlugin
  */
 export class UIPEditor extends UIPPlugin {
   public static is = 'uip-editor';
-  /** Default [config]{@link EditorConfig} used by editor. */
+  /** Default [config]{@link EditorConfig} instance. */
   public static defaultOptions = {
     theme: 'ace/theme/chrome',
     mode: 'ace/mode/html',
@@ -43,9 +38,10 @@ export class UIPEditor extends UIPPlugin {
   /** Editor's [config]{@link EditorConfig} passed through attribute. */
   @jsonAttr()
   public editorConfig: EditorConfig;
+  /** Wrapped ACE editor instance. */
   protected editor: Ace.Editor;
 
-  /** Merge [default config]{@link defaultOptions} with editor's [config]{@link editorConfig}. */
+  /** {@link editorConfig} merged with {@link defaultOptions}. */
   protected get mergedEditorConfig(): EditorConfig {
     const type = (this.constructor as typeof UIPEditor);
     return Object.assign({}, type.defaultOptions, this.editorConfig || {});

src/options/options.ts

@@ -7,8 +7,8 @@ import {UIPEditor} from '../editor/editor';
 import {UIPPlugin} from '../core/plugin';
 
 /**
- * Component which provides controls for changing UIP visual appearance.
- * @see {@link UIPPlugin}
+ * Custom element to provide controls for changing UIP visual appearance.
+ * @extends UIPPlugin
  */
 export class UIPOptions extends UIPPlugin {
   static is = 'uip-options';
@@ -138,7 +138,10 @@ export class UIPOptions extends UIPPlugin {
     this.changeEditorTheme(theme);
   }
 
-  /** Apply horizontal mode for mobile breakpoints. */
+  /**
+   * Callback to track resize event.
+   * Applies horizontal mode for mobile breakpoints.
+   */
   @bind
   protected _onResize() {
     (UIPOptions._conditionQuery.matches)

src/preview/preview.ts

@@ -2,8 +2,8 @@ import {bind} from '@exadel/esl/modules/esl-utils/decorators/bind';
 import {UIPPlugin} from '../core/plugin';
 
 /**
- * Component that displays active markup.
- * @see {@link UIPPlugin}
+ * Custom element that displays active markup.
+ * @extends UIPPlugin
  */
 export class UIPPreview extends UIPPlugin {
   static is = 'uip-preview';

src/settings/setting/bool-setting/bool-setting.ts

@@ -6,28 +6,28 @@ import TokenListUtils from '../../../utils/token-list/token-list-utils';
 import {WARN} from '../../../utils/warn-messages/warn';
 
 /**
- * Custom setting for adding/removing attributes or appending values to attribute.
- * @see {@link UIPSetting}
+ * Custom setting to add/remove attributes or append values to attribute.
+ * @extends UIPSetting
  */
 export class UIPBoolSetting extends UIPSetting {
   public static is = 'uip-bool-setting';
-  /** Class added when setting has inconsistent state. */
+  /** CSS Class added when setting has inconsistent state. */
   public static inconsistencyClass = 'inconsistency-marker';
 
   /** Setting's visible name. */
   @attr({defaultValue: ''}) public label: string;
   /**
-   * Value used for updating [attribute's]{@link UIPSetting#attribute} value.
+   * Value for updating [attribute's]{@link UIPSetting#attribute} value.
    * If it's unset, setting adds/removes [attribute]{@link UIPSetting#attribute}.
    */
   @attr({defaultValue: ''}) public value: string;
   /**
-   * Attribute which sets mode for setting.
-   * Replace - replacing [attribute's]{@link UIPSetting#attribute} value with setting's value.
-   * Append - appending [attribute's]{@link UIPSetting#attribute} value to attribute's value.
+   * Attribute to set mode for setting.
+   * `replace` - replacing [attribute's]{@link UIPSetting#attribute} value with setting's value.
+   * `append` - appending [attribute's]{@link UIPSetting#attribute} value to attribute's value.
    */
   @attr({defaultValue: 'replace'}) public mode: 'replace' | 'append';
-  /** Checkbox field for changing setting's value. */
+  /** Checkbox field to change setting's value. */
   protected $field: HTMLInputElement;
 
   protected connectedCallback() {

src/settings/setting/select-setting/select-setting.ts

@@ -10,7 +10,7 @@ import type {ESLSelect} from '@exadel/esl/modules/esl-forms/esl-select/core';
 
 /**
  * Custom setting for selecting attribute's value.
- * @see {@link UIPSetting}
+ * @extends UIPSetting
  */
 export class UIPSelectSetting extends UIPSetting {
   public static is = 'uip-select-setting';
@@ -20,14 +20,14 @@ export class UIPSelectSetting extends UIPSetting {
   /** Setting's visible name. */
   @attr({defaultValue: ''}) public label: string;
   /**
-   * Attribute which sets mode for setting.
-   * Replace - replacing [attribute's]{@link UIPSetting#attribute} value with setting's value.
-   * Append - appending [attribute's]{@link UIPSetting#attribute} value to attribute's value.
+   * Attribute to set mode for setting.
+   * `replace` - replacing [attribute's]{@link UIPSetting#attribute} value with setting's value.
+   * `append` - appending [attribute's]{@link UIPSetting#attribute} value to attribute's value.
    */
   @attr({defaultValue: 'replace'}) public mode: 'replace' | 'append';
   /** Indicates whether setting supports multiple values selected or not. */
   @boolAttr() public multiple: boolean;
-  /** Select field for changing setting's value. */
+  /** Select field to change setting's value. */
   protected $field: ESLSelect;
 
   protected get settingOptions(): string[] {

src/settings/setting/setting.ts

@@ -7,8 +7,9 @@ import {UIPSettings} from '../settings';
 import {WARN} from '../../utils/warn-messages/warn';
 
 /**
- * Component for manipulating with elements attributes. Custom settings should extend
- * this class if you want them to be connected with {@link UIPSettings}.
+ * Custom element for manipulating with elements attributes.
+ * Custom settings should extend this class
+ * to become connected with {@link UIPSettings}.
  */
 export abstract class UIPSetting extends ESLBaseElement {
   static is = 'uip-setting';
@@ -59,7 +60,7 @@ export abstract class UIPSetting extends ESLBaseElement {
 
   /**
    * Change markup in {@link UIPStateModel}
-   * according to setting's value.
+   * with setting's value.
    */
   public applyTo(model: UIPStateModel): void {
     const cfg: ChangeAttrConfig = {
@@ -72,7 +73,7 @@ export abstract class UIPSetting extends ESLBaseElement {
   }
 
   /**
-   * Update setting's value according to
+   * Update setting's value with
    * active markup in {@link UIPStateModel}.
    */
   public updateFrom(model: UIPStateModel): void {
@@ -89,7 +90,7 @@ export abstract class UIPSetting extends ESLBaseElement {
 
   /**
    * Check whether setting's value is valid or not.
-   * Can be used for custom validation.
+   * Use for custom validation.
    */
   protected isValid(): boolean {
     return true;

src/settings/setting/text-setting/text-setting.ts

@@ -5,14 +5,14 @@ import {WARN} from '../../../utils/warn-messages/warn';
 
 /**
  * Custom setting for inputting attribute's value.
- * @see {@link UIPSetting}
+ * @extends UIPSetting
  */
 export class UIPTextSetting extends UIPSetting {
   public static is = 'uip-text-setting';
 
   /** Setting's visible name. */
   @attr({defaultValue: ''}) public label: string;
-  /** Text input for changing setting's value. */
+  /** Text input to change setting's value. */
   protected $field: HTMLInputElement;
 
   protected connectedCallback() {

src/settings/settings.ts

@@ -5,15 +5,15 @@ import {CSSClassUtils, memoize} from '@exadel/esl';
 import {UIPPlugin} from '../core/plugin';
 
 /**
- * Container class for [settings]{@link UIPSetting}.
- * @see {@link UIPPlugin}
+ * Custom element, container for [settings]{@link UIPSetting}.
+ * @extends UIPPlugin
  */
 export class UIPSettings extends UIPPlugin {
   public static is = 'uip-settings';
 
   /**
-   * Attribute which sets all inner [settings']{@link UIPSetting}
-   * [targets]{@link UIPSetting#target} to its value.
+   * Attribute to set all inner [settings']{@link UIPSetting}
+   * [targets]{@link UIPSetting#target}.
    */
   @attr() public target: string;
   @attr({defaultValue: 'Settings'}) public label: string;

src/snippets/snippets.ts

@@ -4,15 +4,15 @@ import {UIPPlugin} from '../core/plugin';
 
 /**
  * Container class for snippets (component's templates).
- * @see {@link UIPPlugin}
+ * @extends UIPPlugin
  */
 export class UIPSnippets extends UIPPlugin {
   public static is = 'uip-snippets';
-  /** Class added to active snippet. */
+  /** CSS Class added to active snippet. */
   public static ACTIVE_CLASS = 'active';
-  /** Class for snippets list items. */
+  /** CSS Class for snippets list items. */
   public static ITEM_CLASS = 'snippets-list-item';
-  /** Selector for snippets. */
+  /** CSS query for snippets. */
   public static CONTENT_SEL = '[uip-snippet]';
 
   protected connectedCallback() {