chore(datetime): Add descriptions public API #6271

Author: IvayloG

projects/igniteui-angular/src/lib/directives/date-time-editor/date-time-editor.directive.ts

@@ -12,6 +12,28 @@ import {
 } from '../../date-picker/date-picker.utils';
 import { IgxDateTimeEditorEventArgs, DatePartInfo, DatePart } from './date-time-editor.common';
 
+/**
+ * Date Time Editor provides a functionality to input, edit and format date and time.
+ *
+ * @igxModule IgxDateTimeEditorModule
+ *
+ * @igxKeywords date, time, editor
+ *
+ * @igxGroup Scheduling
+ *
+ * @remarks
+ *
+ * The Ignite UI Date Time Editor Directive makes it easy for developers to manipulate date/time user input. It requires input in a specified or
+ * default input format which is visible in the input element as a placeholder. It allows to input only date(ex: 'dd/MM/yyyy'), only time(ex:'HH:mm tt') or both at once if needed.
+ * Supports display format that may differ from the input format. Provides methods to increment and decrement any specific/targeted `DatePart`.
+ *
+ * @example
+ * ```html
+ * <igx-input-group>
+ *   <input type="text" igxInput [igxDateTimeEditor]="'dd/MM/yyyy'" [displayFormat]="'shortDate'" [(ngModel)]="date"/>
+ * </igx-input-group>
+ * ```
+ */
 @Directive({
   selector: '[igxDateTimeEditor]',
   exportAs: 'igxDateTimeEditor',
@@ -20,28 +42,65 @@ import { IgxDateTimeEditorEventArgs, DatePartInfo, DatePart } from './date-time-
   ]
 })
 export class IgxDateTimeEditorDirective extends IgxMaskDirective implements OnInit, ControlValueAccessor {
+  /**
+  * An @Input property that allows you to set the locale settings used in `displayFormat`.
+  * @example
+  *```html
+  * <input igxDateTimeEditor [locale]="'en'">
+  *```
+  */
   @Input()
   public locale = 'en';
 
+/**
+  * An @Input property that allows you to set the minimum possible value the editor will allow.
+  * @example
+  *```html
+  * <input igxDateTimeEditor [minValue]="minDate">
+  *```
+  */
   @Input()
   public minValue: string | Date;
 
+  /**
+  * An @Input property that allows you to set the maximum possible value the editor will allow.
+  * @example
+  *```html
+  * <input igxDateTimeEditor [maxValue]="maxDate">
+  *```
+  */
   @Input()
   public maxValue: string | Date;
 
-  @Input()
-  public promptChar: string;
-
+  /**
+   * An @Input property that allows you to specify if the currently spun date segment should loop over.
+   * @example
+   *```html
+   * <input igxDateTimeEditor [isSpinLoop]="false">
+   *```
+   */
   @Input()
   public isSpinLoop = true;
 
+  /**
+   * An @Input property that allows you to set both pre-defined format options such as `shortDate` and `longDate`,
+   * as well as constructed format string using characters supported by `DatePipe`, e.g. `EE/MM/yyyy`.
+   * @example
+   *```html
+   * <input igxDateTimeEditor [displayFormat]="'shortDate'">
+   *```
+   */
   @Input()
   public displayFormat: string;
 
-  public get inputFormat(): string {
-    return this._format;
-  }
-
+  /**
+   * An @Input property that allows you to get/set the expected user input format(and placeholder).
+   *  for the editor.
+   * @example
+   *```html
+   * <input [igxDateTimeEditor]="'dd/MM/yyyy'">
+   *```
+   */
   @Input(`igxDateTimeEditor`)
   public set inputFormat(value: string) {
     if (value) {
@@ -51,19 +110,44 @@ export class IgxDateTimeEditorDirective extends IgxMaskDirective implements OnIn
     this.mask = value.indexOf('tt') !== -1 ? mask.substring(0, mask.length - 2) + 'LL' : mask;
   }
 
-  public get value() {
-    return this._value;
+  public get inputFormat(): string {
+    return this._format;
   }
 
+  /**
+   * An @Input property that gets/sets the component date value.
+   * @example
+   * ```html
+   * <input igxDateTimeEditor [value]="date">
+   * ```
+   */
   @Input()
   public set value(value: Date) {
     this._value = value;
     this.updateMask();
   }
 
+  public get value() {
+    return this._value;
+  }
+
+  /**
+   * Emitted when the editor's value has changed.
+   * @example
+   * ```html
+   * <input igxDateTimeEditor (valueChanged)="onValueChanged($event)"/>
+   * ```
+   */
   @Output()
   public valueChanged = new EventEmitter<IgxDateTimeEditorEventArgs>();
 
+  /**
+   * Emitted when the editor is not within a specified range.
+   * @example
+   * ```html
+   * <input igxDateTimeEditor [minValue]="minDate" [maxValue]="maxDate" (validationFailed)="onValidationFailed($event)"/>
+   * ```
+   */
   @Output()
   public validationFailed = new EventEmitter<IgxDateTimeEditorEventArgs>();
 
@@ -110,18 +194,24 @@ export class IgxDateTimeEditorDirective extends IgxMaskDirective implements OnIn
     this._document = this.document as Document;
   }
 
-  /** @hidden */
+  /** @hidden @internal */
   public ngOnInit(): void {
     this._dateTimeFormatParts = DatePickerUtil.parseDateTimeFormat(this.inputFormat);
     this.renderer.setAttribute(this.nativeElement, 'placeholder', this.inputFormat);
     this.updateMask();
   }
-
+  /**
+   * Clear the input element value.
+   */
   public clear(): void {
     this.updateValue(null);
     this.updateMask();
   }
 
+  /**
+  * Increment specified DatePart.
+  * @param datePart The optional DatePart to increment. Defaults to Date or Hours(when Date is absent from the inputFormat - ex:'HH:mm').
+  */
   public increment(datePart?: DatePart): void {
     const newValue = datePart
       ? this.calculateValueOnSpin(datePart, 1)
@@ -130,6 +220,11 @@ export class IgxDateTimeEditorDirective extends IgxMaskDirective implements OnIn
     this.updateMask();
   }
 
+  /**
+  * Decrement specified DatePart.
+  *
+  * @param datePart The optional DatePart to decrement. Defaults to Date or Hours(when Date is absent from the inputFormat - ex:'HH:mm').
+  */
   public decrement(datePart?: DatePart): void {
     const newValue = datePart
       ? this.calculateValueOnSpin(datePart, -1)
@@ -138,21 +233,21 @@ export class IgxDateTimeEditorDirective extends IgxMaskDirective implements OnIn
     this.updateMask();
   }
 
-  /** @hidden */
+  /** @hidden @internal */
   public writeValue(value: any): void {
     this.value = value;
   }
 
-  /** @hidden */
+  /** @hidden @internal */
   public registerOnChange(fn: any): void { this.onChangeCallback = fn; }
 
-  /** @hidden */
+  /** @hidden @internal */
   public registerOnTouched(fn: any): void { this.onTouchCallback = fn; }
 
-  /** @hidden */
+  /** @hidden @internal */
   public setDisabledState?(isDisabled: boolean): void { }
 
-  /** @hidden */
+  /** @hidden @internal */
   public onKeyDown(event: KeyboardEvent) {
     super.onKeyDown(event);
     if (event.key === KEYS.UP_ARROW || event.key === KEYS.UP_ARROW_IE ||
@@ -169,15 +264,15 @@ export class IgxDateTimeEditorDirective extends IgxMaskDirective implements OnIn
     this.moveCursor(event);
   }
 
-  /** @hidden */
+  /** @hidden @internal */
   public onFocus(): void {
     this._isFocused = true;
     this.onTouchCallback();
     this.updateMask();
     super.onFocus();
   }
 
-  /** @hidden */
+  /** @hidden @internal */
   public onBlur(event): void {
     this._isFocused = false;
     this.updateValue(this.value);
@@ -186,7 +281,7 @@ export class IgxDateTimeEditorDirective extends IgxMaskDirective implements OnIn
     super.onBlur(event);
   }
 
-  /** @hidden */
+  /** @hidden @internal */
   public onInputChanged(): void {
     // the mask must be updated before any date operations
     super.onInputChanged();
@@ -204,7 +299,7 @@ export class IgxDateTimeEditorDirective extends IgxMaskDirective implements OnIn
     }
   }
 
-  /** @hidden */
+  /** @hidden @internal */
   public updateMask() {
     if (!this.value || !this.isValidDate(this.value)) {
       this.inputValue = this.emptyMask;

projects/igniteui-angular/src/lib/drop-down/index.ts

@@ -11,7 +11,7 @@ import { IgxDropDownItemBaseDirective } from './drop-down-item.base';
 
 export * from './drop-down.component';
 export * from './drop-down-item.component';
-export { ISelectionEventArgs, IDropDownNavigationDirective,  } from './drop-down.common';
+export { ISelectionEventArgs, IDropDownNavigationDirective } from './drop-down.common';
 export * from './drop-down-navigation.directive';
 export * from './drop-down.base';
 export * from './drop-down-item.base';