From 34642ea4ef50beb1b75df430f3f05503e0bb7ce7 Mon Sep 17 00:00:00 2001 From: Jeremy Elbourn Date: Fri, 16 Dec 2016 15:56:14 -0800 Subject: [PATCH] docs: fill out jsdoc for button, checkbox, and radio (#2252) * docs: fill out jsdoc for button, checkbox, and radio * Fix bad rename, re-add isAriaDisabled --- src/lib/button-toggle/button-toggle.ts | 3 +- src/lib/button/button.html | 6 +-- src/lib/button/button.ts | 26 +++++------ src/lib/checkbox/checkbox.html | 2 +- src/lib/checkbox/checkbox.ts | 62 +++++++++++--------------- src/lib/radio/radio.html | 4 +- src/lib/radio/radio.ts | 61 ++++++++++++++++--------- 7 files changed, 86 insertions(+), 78 deletions(-) diff --git a/src/lib/button-toggle/button-toggle.ts b/src/lib/button-toggle/button-toggle.ts index a88b510f2e4..b74de147c58 100644 --- a/src/lib/button-toggle/button-toggle.ts +++ b/src/lib/button-toggle/button-toggle.ts @@ -34,6 +34,7 @@ export type ToggleType = 'checkbox' | 'radio'; /** * Provider Expression that allows md-button-toggle-group to register as a ControlValueAccessor. * This allows it to support [(ngModel)]. + * @docs-private */ export const MD_BUTTON_TOGGLE_GROUP_VALUE_ACCESSOR: any = { provide: NG_VALUE_ACCESSOR, @@ -43,7 +44,7 @@ export const MD_BUTTON_TOGGLE_GROUP_VALUE_ACCESSOR: any = { var _uniqueIdCounter = 0; -/** A simple change event emitted by either MdButtonToggle or MdButtonToggleGroup. */ +/** Change event object emitted by MdButtonToggle. */ export class MdButtonToggleChange { source: MdButtonToggle; value: any; diff --git a/src/lib/button/button.html b/src/lib/button/button.html index a82eb530bbf..281f5f5101e 100644 --- a/src/lib/button/button.html +++ b/src/lib/button/button.html @@ -1,8 +1,8 @@
diff --git a/src/lib/button/button.ts b/src/lib/button/button.ts index 890ea7df356..d3129c2752d 100644 --- a/src/lib/button/button.ts +++ b/src/lib/button/button.ts @@ -47,24 +47,22 @@ export class MdButton { private _disableRipple: boolean = false; private _disabled: boolean = null; + /** Whether the ripple effect for this button is disabled. */ @Input() get disableRipple() { return this._disableRipple; } set disableRipple(v) { this._disableRipple = coerceBooleanProperty(v); } + /** Whether the button is disabled. */ @Input() get disabled() { return this._disabled; } set disabled(value: boolean) { this._disabled = coerceBooleanProperty(value) ? true : null; } constructor(private _elementRef: ElementRef, private _renderer: Renderer) { } + /** The color of the button. Can be `primary`, `accent`, or `warn`. */ @Input() - get color(): string { - return this._color; - } - - set color(value: string) { - this._updateColor(value); - } + get color(): string { return this._color; } + set color(value: string) { this._updateColor(value); } _setMousedown() { // We only *show* the focus style when focus has come to the button via the keyboard. @@ -95,16 +93,16 @@ export class MdButton { this._isKeyboardFocused = false; } - /** TODO(hansl): e2e test this function. */ - focus() { + /** Focuses the button. */ + focus(): void { this._renderer.invokeElementMethod(this._elementRef.nativeElement, 'focus'); } - getHostElement() { + _getHostElement() { return this._elementRef.nativeElement; } - isRoundButton() { + _isRoundButton() { const el = this._elementRef.nativeElement; return el.hasAttribute('md-icon-button') || el.hasAttribute('md-fab') || @@ -122,6 +120,7 @@ export class MdButton { inputs: ['color', 'disabled', 'disableRipple'], host: { '[attr.disabled]': 'disabled', + '[attr.aria-disabled]': '_isAriaDisabled', '[class.md-button-focus]': '_isKeyboardFocused', '(mousedown)': '_setMousedown()', '(focus)': '_setKeyboardFocus()', @@ -137,14 +136,13 @@ export class MdAnchor extends MdButton { super(elementRef, renderer); } + /** @docs-private */ @HostBinding('tabIndex') get tabIndex(): number { return this.disabled ? -1 : 0; } - /** Gets the aria-disabled value for the component, which must be a string for Dart. */ - @HostBinding('attr.aria-disabled') - get isAriaDisabled(): string { + get _isAriaDisabled(): string { return this.disabled ? 'true' : 'false'; } diff --git a/src/lib/checkbox/checkbox.html b/src/lib/checkbox/checkbox.html index fba084ce10a..b67f3aae244 100644 --- a/src/lib/checkbox/checkbox.html +++ b/src/lib/checkbox/checkbox.html @@ -16,7 +16,7 @@ (change)="_onInteractionEvent($event)" (click)="_onInputClick($event)">
diff --git a/src/lib/checkbox/checkbox.ts b/src/lib/checkbox/checkbox.ts index 89d8d01b36a..ad133211732 100644 --- a/src/lib/checkbox/checkbox.ts +++ b/src/lib/checkbox/checkbox.ts @@ -20,14 +20,13 @@ import {MdRippleModule, DefaultStyleCompatibilityModeModule} from '../core'; import {ViewportRuler} from '../core/overlay/position/viewport-ruler'; -/** - * Monotonically increasing integer used to auto-generate unique ids for checkbox components. - */ +/** Monotonically increasing integer used to auto-generate unique ids for checkbox components. */ let nextId = 0; /** - * Provider Expression that allows md-checkbox to register as a ControlValueAccessor. This allows it - * to support [(ngModel)]. + * Provider Expression that allows md-checkbox to register as a ControlValueAccessor. + * This allows it to support [(ngModel)]. + * @docs-private */ export const MD_CHECKBOX_CONTROL_VALUE_ACCESSOR: any = { provide: NG_VALUE_ACCESSOR, @@ -37,6 +36,7 @@ export const MD_CHECKBOX_CONTROL_VALUE_ACCESSOR: any = { /** * Represents the different states that require custom transitions between them. + * @docs-private */ export enum TransitionCheckState { /** The initial state of the component before any user interaction. */ @@ -49,7 +49,7 @@ export enum TransitionCheckState { Indeterminate } -// A simple change event emitted by the MdCheckbox component. +/** Change event object emitted by MdCheckbox. */ export class MdCheckboxChange { source: MdCheckbox; checked: boolean; @@ -73,7 +73,7 @@ export class MdCheckboxChange { '[class.md-checkbox-checked]': 'checked', '[class.md-checkbox-disabled]': 'disabled', '[class.md-checkbox-align-end]': 'align == "end"', - '[class.md-checkbox-focused]': 'hasFocus', + '[class.md-checkbox-focused]': '_hasFocus', }, providers: [MD_CHECKBOX_CONTROL_VALUE_ACCESSOR], encapsulation: ViewEncapsulation.None, @@ -97,18 +97,19 @@ export class MdCheckbox implements ControlValueAccessor { /** Whether the ripple effect on click should be disabled. */ private _disableRipple: boolean; + /** Whether the ripple effect for this checkbox is disabled. */ @Input() get disableRipple(): boolean { return this._disableRipple; } set disableRipple(value) { this._disableRipple = coerceBooleanProperty(value); } - /** ID to be applied to the `input` element */ + /** ID of the native input element inside `` */ get inputId(): string { return `input-${this.id}`; } private _required: boolean; - /** Whether the checkbox is required or not. */ + /** Whether the checkbox is required. */ @Input() get required(): boolean { return this._required; } set required(value) { this._required = coerceBooleanProperty(value); } @@ -118,18 +119,12 @@ export class MdCheckbox implements ControlValueAccessor { private _disabled: boolean = false; - /** - * Whether the checkbox is disabled. When the checkbox is disabled it cannot be interacted with. - * The correct ARIA attributes are applied to denote this to assistive technology. - */ + /** Whether the checkbox is disabled. */ @Input() get disabled(): boolean { return this._disabled; } set disabled(value) { this._disabled = coerceBooleanProperty(value); } - /** - * The tabindex attribute for the checkbox. Note that when the checkbox is disabled, the attribute - * on the host element will be removed. It will be placed back when the checkbox is re-enabled. - */ + /** @docs-private */ @Input() tabindex: number = 0; /** Name value will be applied to the input element if present */ @@ -141,7 +136,10 @@ export class MdCheckbox implements ControlValueAccessor { /** The native ` element */ @ViewChild('input') _inputElement: ElementRef; - /** Called when the checkbox is blurred. Needed to properly implement ControlValueAccessor. */ + /** + * Called when the checkbox is blurred. Needed to properly implement ControlValueAccessor. + * @docs-private + */ onTouched: () => any = () => {}; private _currentAnimationClass: string = ''; @@ -156,7 +154,7 @@ export class MdCheckbox implements ControlValueAccessor { private _controlValueAccessorChangeFn: (value: any) => void = (value) => {}; - hasFocus: boolean = false; + _hasFocus: boolean = false; constructor(private _renderer: Renderer, private _elementRef: ElementRef, @@ -205,15 +203,10 @@ export class MdCheckbox implements ControlValueAccessor { } } - /** Sets the color of the checkbox */ + /** The color of the button. Can be `primary`, `accent`, or `warn`. */ @Input() - get color(): string { - return this._color; - } - - set color(value: string) { - this._updateColor(value); - } + get color(): string { return this._color; } + set color(value: string) { this._updateColor(value); } _updateColor(newColor: string) { this._setElementColor(this._color, false); @@ -283,19 +276,17 @@ export class MdCheckbox implements ControlValueAccessor { /** Informs the component when the input has focus so that we can style accordingly */ _onInputFocus() { - this.hasFocus = true; + this._hasFocus = true; } /** Informs the component when we lose focus in order to style accordingly */ _onInputBlur() { - this.hasFocus = false; + this._hasFocus = false; this.onTouched(); } - /** - * Toggles the `checked` value between true and false - */ - toggle() { + /** Toggles the `checked` state of the checkbox. */ + toggle(): void { this.checked = !this.checked; } @@ -320,7 +311,8 @@ export class MdCheckbox implements ControlValueAccessor { } } - focus() { + /** Focuses the checkbox. */ + focus(): void { this._renderer.invokeElementMethod(this._inputElement.nativeElement, 'focus'); this._onInputFocus(); } @@ -366,7 +358,7 @@ export class MdCheckbox implements ControlValueAccessor { return `md-checkbox-anim-${animSuffix}`; } - getHostElement() { + _getHostElement() { return this._elementRef.nativeElement; } } diff --git a/src/lib/radio/radio.html b/src/lib/radio/radio.html index 9fdf1080dc6..567896528cc 100644 --- a/src/lib/radio/radio.html +++ b/src/lib/radio/radio.html @@ -6,7 +6,7 @@
@@ -25,7 +25,7 @@ (click)="_onInputClick($event)"> -
+
diff --git a/src/lib/radio/radio.ts b/src/lib/radio/radio.ts index f455a24f6b3..b710d776597 100644 --- a/src/lib/radio/radio.ts +++ b/src/lib/radio/radio.ts @@ -32,6 +32,7 @@ import {ViewportRuler} from '../core/overlay/position/viewport-ruler'; /** * Provider Expression that allows md-radio-group to register as a ControlValueAccessor. This * allows it to support [(ngModel)] and ngControl. + * @docs-private */ export const MD_RADIO_GROUP_CONTROL_VALUE_ACCESSOR: any = { provide: NG_VALUE_ACCESSOR, @@ -39,22 +40,17 @@ export const MD_RADIO_GROUP_CONTROL_VALUE_ACCESSOR: any = { multi: true }; -// TODO(mtlin): -// Ink ripple is currently placeholder. -// Determine motion spec for button transitions. -// Design review. -// RTL -// Support forms API. -// Use ChangeDetectionStrategy.OnPush - var _uniqueIdCounter = 0; -/** A simple change event emitted by either MdRadioButton or MdRadioGroup. */ +/** Change event object emitted by MdRadio and MdRadioGroup. */ export class MdRadioChange { source: MdRadioButton; value: any; } +/** + * A group of radio buttons. May contain one or more `` elements. + */ @Directive({ selector: 'md-radio-group, mat-radio-group', providers: [MD_RADIO_GROUP_CONTROL_VALUE_ACCESSOR], @@ -86,10 +82,17 @@ export class MdRadioGroup implements AfterContentInit, ControlValueAccessor { /** The method to be called in order to update ngModel */ _controlValueAccessorChangeFn: (value: any) => void = (value) => {}; - /** onTouch function registered via registerOnTouch (ControlValueAccessor). */ + /** + * onTouch function registered via registerOnTouch (ControlValueAccessor). + * @docs-private + */ onTouched: () => any = () => {}; - /** Event emitted when the group value changes. */ + /** + * Event emitted when the group value changes. + * Change events are only emitted when the value changes due to user interaction with + * a radio button (the same behavior as ``). + */ @Output() change: EventEmitter = new EventEmitter(); @@ -97,6 +100,7 @@ export class MdRadioGroup implements AfterContentInit, ControlValueAccessor { @ContentChildren(forwardRef(() => MdRadioButton)) _radios: QueryList = null; + /** Name of the radio button group. All radio buttons inside this group will use this name. */ @Input() get name(): string { return this._name; @@ -107,7 +111,8 @@ export class MdRadioGroup implements AfterContentInit, ControlValueAccessor { this._updateRadioButtonNames(); } - @Input() align: 'start' | 'end'; + /** Alignment of the radio-buttons relative to their labels. Can be 'before' or 'after'. */ + @Input() align: 'before' | 'after'; @Input() get disabled(): boolean { @@ -228,7 +233,9 @@ export class MdRadioGroup implements AfterContentInit, ControlValueAccessor { } } - +/** + * A radio-button. May be inside of + */ @Component({ moduleId: module.id, selector: 'md-radio-button, mat-radio-button', @@ -271,15 +278,20 @@ export class MdRadioButton implements OnInit { /** The parent radio group. May or may not be present. */ radioGroup: MdRadioGroup; + /** Whether the ripple effect for this radio button is disabled. */ @Input() get disableRipple(): boolean { return this._disableRipple; } set disableRipple(value) { this._disableRipple = coerceBooleanProperty(value); } - /** Event emitted when the group value changes. */ + /** + * Event emitted when the checked state of this radio button changes. + * Change events are only emitted when the value changes due to user interaction with + * the radio button (the same behavior as ``). + */ @Output() change: EventEmitter = new EventEmitter(); - /** The native ` element */ + /** The native `` element */ @ViewChild('input') _inputElement: ElementRef; constructor(@Optional() radioGroup: MdRadioGroup, @@ -298,10 +310,12 @@ export class MdRadioButton implements OnInit { }); } + /** ID of the native input element inside `` */ get inputId(): string { return `${this.id}-input`; } + /** Whether this radio button is checked. */ @HostBinding('class.md-radio-checked') @Input() get checked(): boolean { @@ -327,7 +341,7 @@ export class MdRadioButton implements OnInit { } } - /** MdRadioGroup reads this to assign its own value. */ + /** The value of this radio button. */ @Input() get value(): any { return this._value; @@ -349,17 +363,19 @@ export class MdRadioButton implements OnInit { } } - private _align: 'start' | 'end'; + private _align: 'before' | 'after'; + /** Alignment of the radio-button relative to their labels. Can be 'before' or 'after'. */ @Input() - get align(): 'start' | 'end' { - return this._align || (this.radioGroup != null && this.radioGroup.align) || 'start'; + get align(): 'before' | 'after' { + return this._align || (this.radioGroup != null && this.radioGroup.align) || 'before'; } - set align(value: 'start' | 'end') { + set align(value: 'before' | 'after') { this._align = value; } + /** Whether the radio button is disabled. */ @HostBinding('class.md-radio-disabled') @Input() get disabled(): boolean { @@ -401,7 +417,8 @@ export class MdRadioButton implements OnInit { this._isFocused = true; } - focus() { + /** Focuses the radio button. */ + focus(): void { this._renderer.invokeElementMethod(this._inputElement.nativeElement, 'focus'); this._onInputFocus(); } @@ -448,7 +465,7 @@ export class MdRadioButton implements OnInit { } } - getHostElement() { + _getHostElement() { return this._elementRef.nativeElement; } }