Skip to content

Commit 5d08e44

Browse files
shirakabashirakaba
committed
chore(core): update doc comments for on(), once(), addEventListener() and removeEventListener()
1 parent 9be392f commit 5d08e44

File tree

16 files changed

+176
-98
lines changed

16 files changed

+176
-98
lines changed

‎packages/core/data/observable-array/index.ts

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -424,12 +424,16 @@ export class ObservableArray<T> extends Observable {
424424

425425
export interface ObservableArray<T> {
426426
/**
427-
* A basic method signature to hook an event listener (shortcut alias to the addEventListener method).
428-
* @param eventNames - String corresponding to events (e.g. "propertyChange"). Optionally could be used more events separated by `,` (e.g. "propertyChange", "change").
429-
* @param callback - Callback function which will be executed when event is raised.
430-
* @param thisArg - An optional parameter which will be used as `this` context for callback execution.
431-
*/
432-
on(eventNames: string, callback: (data: EventData) => void, thisArg?: any): void;
427+
* Adds a listener for the specified event name.
428+
*
429+
* @param eventName The name of the event.
430+
* @param callback The event listener to add. Will be called when an event of
431+
* the given name is raised.
432+
* @param thisArg An optional parameter which, when set, will be bound as the
433+
* `this` context when the callback is called. Falsy values will be not be
434+
* bound.
435+
*/
436+
on(eventName: string, callback: (data: EventData) => void, thisArg?: any): void;
433437

434438
on(event: 'change', callback: (args: ChangedData<T>) => void, thisArg?: any): void;
435439
}

‎packages/core/data/observable/index.ts

Lines changed: 24 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -150,27 +150,42 @@ export class Observable {
150150
}
151151

152152
/**
153-
* A basic method signature to hook an event listener (shortcut alias to the addEventListener method).
154-
* @param eventName Name of the event to attach to.
155-
* @param callback - Callback function which will be executed when event is raised.
156-
* @param thisArg - An optional parameter which will be used as `this` context for callback execution.
153+
* Adds a listener for the specified event name.
154+
*
155+
* @param eventName The name of the event.
156+
* @param callback The event listener to add. Will be called when an event of
157+
* the given name is raised.
158+
* @param thisArg An optional parameter which, when set, will be bound as the
159+
* `this` context when the callback is called. Falsy values will be not be
160+
* bound.
157161
*/
158162
public on(eventName: string, callback: (data: EventData) => void, thisArg?: any): void {
159163
this.addEventListener(eventName, callback, thisArg);
160164
}
161165

162166
/**
163-
* Adds one-time listener function for the event named `event`.
164-
* @param eventName Name of the event to attach to.
165-
* @param callback A function to be called when the specified event is raised.
166-
* @param thisArg An optional parameter which when set will be used as "this" in callback method call.
167+
* Adds a listener for the specified event name, which, once fired, will
168+
* remove itself.
169+
*
170+
* @param eventName The name of the event.
171+
* @param callback The event listener to add. Will be called when an event of
172+
* the given name is raised.
173+
* @param thisArg An optional parameter which, when set, will be bound as the
174+
* `this` context when the callback is called. Falsy values will be not be
175+
* bound.
167176
*/
168177
public once(eventName: string, callback: (data: EventData) => void, thisArg?: any): void {
169178
this.addEventListener(eventName, callback, thisArg, true);
170179
}
171180

172181
/**
173-
* Shortcut alias to the removeEventListener method.
182+
* Removes the listener(s) for the specified event name.
183+
*
184+
* @param eventName The name of the event.
185+
* @param callback An optional specific event listener to remove (if omitted,
186+
* all event listeners by this name will be removed).
187+
* @param thisArg An optional parameter which, when set, will be used to
188+
* refine search of the correct event listener to be removed.
174189
*/
175190
public off(eventName: string, callback?: (data: EventData) => void, thisArg?: any): void {
176191
this.removeEventListener(eventName, callback, thisArg);

‎packages/core/data/virtual-array/index.ts

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -183,12 +183,16 @@ export class VirtualArray<T> extends Observable {
183183
}
184184
export interface VirtualArray<T> {
185185
/**
186-
* A basic method signature to hook an event listener (shortcut alias to the addEventListener method).
187-
* @param eventNames - String corresponding to events (e.g. "propertyChange"). Optionally could be used more events separated by `,` (e.g. "propertyChange", "change").
188-
* @param callback - Callback function which will be executed when event is raised.
189-
* @param thisArg - An optional parameter which will be used as `this` context for callback execution.
186+
* Adds a listener for the specified event name.
187+
*
188+
* @param eventName The name of the event.
189+
* @param callback The event listener to add. Will be called when an event of
190+
* the given name is raised.
191+
* @param thisArg An optional parameter which, when set, will be bound as the
192+
* `this` context when the callback is called. Falsy values will be not be
193+
* bound.
190194
*/
191-
on(eventNames: string, callback: (data: EventData) => void, thisArg?: any): void;
195+
on(eventName: string, callback: (data: EventData) => void, thisArg?: any): void;
192196
/**
193197
* Raised when still not loaded items are requested.
194198
*/

‎packages/core/ui/action-bar/index.d.ts

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -129,12 +129,16 @@ export class ActionItem extends ViewBase {
129129
actionBar: ActionBar;
130130

131131
/**
132-
* A basic method signature to hook an event listener (shortcut alias to the addEventListener method).
133-
* @param eventNames - String corresponding to events (e.g. "propertyChange"). Optionally could be used more events separated by `,` (e.g. "propertyChange", "change").
134-
* @param callback - Callback function which will be executed when event is raised.
135-
* @param thisArg - An optional parameter which will be used as `this` context for callback execution.
136-
*/
137-
on(eventNames: string, callback: (data: EventData) => void): void;
132+
* Adds a listener for the specified event name.
133+
*
134+
* @param eventName The name of the event.
135+
* @param callback The event listener to add. Will be called when an event of
136+
* the given name is raised.
137+
* @param thisArg An optional parameter which, when set, will be bound as the
138+
* `this` context when the callback is called. Falsy values will be not be
139+
* bound.
140+
*/
141+
on(eventName: string, callback: (data: EventData) => void): void;
138142

139143
/**
140144
* Raised when a tap event occurs.

‎packages/core/ui/button/index.d.ts

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -26,12 +26,16 @@ export class Button extends TextBase {
2626
textWrap: boolean;
2727

2828
/**
29-
* A basic method signature to hook an event listener (shortcut alias to the addEventListener method).
30-
* @param eventNames - String corresponding to events (e.g. "propertyChange"). Optionally could be used more events separated by `,` (e.g. "propertyChange", "change").
31-
* @param callback - Callback function which will be executed when event is raised.
32-
* @param thisArg - An optional parameter which will be used as `this` context for callback execution.
29+
* Adds a listener for the specified event name.
30+
*
31+
* @param eventName The name of the event.
32+
* @param callback The event listener to add. Will be called when an event of
33+
* the given name is raised.
34+
* @param thisArg An optional parameter which, when set, will be bound as the
35+
* `this` context when the callback is called. Falsy values will be not be
36+
* bound.
3337
*/
34-
on(eventNames: string, callback: (data: EventData) => void, thisArg?: any): void;
38+
on(eventName: string, callback: (data: EventData) => void, thisArg?: any): void;
3539

3640
/**
3741
* Raised when a tap event occurs.

‎packages/core/ui/core/view/index.d.ts

Lines changed: 18 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -590,20 +590,27 @@ export abstract class View extends ViewCommon {
590590
public getGestureObservers(type: GestureTypes): Array<GesturesObserver> | undefined;
591591

592592
/**
593-
* Removes listener(s) for the specified event name.
594-
* @param eventNames Comma delimited names of the events or gesture types the specified listener is associated with.
595-
* @param callback An optional parameter pointing to a specific listener. If not defined, all listeners for the event names will be removed.
596-
* @param thisArg An optional parameter which when set will be used to refine search of the correct callback which will be removed as event listener.
593+
* Removes the listener(s) for the specified event name.
594+
*
595+
* @param eventName The name of the event.
596+
* @param callback An optional specific event listener to remove (if omitted,
597+
* all event listeners by this name will be removed).
598+
* @param thisArg An optional parameter which, when set, will be used to
599+
* refine search of the correct event listener to be removed.
597600
*/
598-
off(eventNames: string, callback?: (args: EventData) => void, thisArg?: any);
601+
off(eventName: string, callback?: (args: EventData) => void, thisArg?: any);
599602

600603
/**
601-
* A basic method signature to hook an event listener (shortcut alias to the addEventListener method).
602-
* @param eventNames - String corresponding to events (e.g. "propertyChange"). Optionally could be used more events separated by `,` (e.g. "propertyChange", "change") or you can use gesture types.
603-
* @param callback - Callback function which will be executed when event is raised.
604-
* @param thisArg - An optional parameter which will be used as `this` context for callback execution.
605-
*/
606-
on(eventNames: string, callback: (args: EventData) => void, thisArg?: any);
604+
* Adds a listener for the specified event name.
605+
*
606+
* @param eventName The name of the event.
607+
* @param callback The event listener to add. Will be called when an event of
608+
* the given name is raised.
609+
* @param thisArg An optional parameter which, when set, will be bound as the
610+
* `this` context when the callback is called. Falsy values will be not be
611+
* bound.
612+
*/
613+
on(eventName: string, callback: (args: EventData) => void, thisArg?: any);
607614

608615
/**
609616
* Raised when a loaded event occurs.

‎packages/core/ui/frame/index.d.ts

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -225,12 +225,16 @@ export class Frame extends FrameBase {
225225
//@endprivate
226226

227227
/**
228-
* A basic method signature to hook an event listener (shortcut alias to the addEventListener method).
229-
* @param eventNames - String corresponding to events (e.g. "propertyChange"). Optionally could be used more events separated by `,` (e.g. "propertyChange", "change").
230-
* @param callback - Callback function which will be executed when event is raised.
231-
* @param thisArg - An optional parameter which will be used as `this` context for callback execution.
232-
*/
233-
on(eventNames: string, callback: (args: EventData) => void, thisArg?: any): void;
228+
* Adds a listener for the specified event name.
229+
*
230+
* @param eventName The name of the event.
231+
* @param callback The event listener to add. Will be called when an event of
232+
* the given name is raised.
233+
* @param thisArg An optional parameter which, when set, will be bound as the
234+
* `this` context when the callback is called. Falsy values will be not be
235+
* bound.
236+
*/
237+
on(eventName: string, callback: (args: EventData) => void, thisArg?: any): void;
234238

235239
/**
236240
* Raised when navigation to the page has started.

‎packages/core/ui/image-cache/index.d.ts

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -80,12 +80,16 @@ export class Cache extends Observable {
8080
clear(): void;
8181

8282
/**
83-
* A basic method signature to hook an event listener (shortcut alias to the addEventListener method).
84-
* @param eventNames - String corresponding to events (e.g. "propertyChange"). Optionally could be used more events separated by `,` (e.g. "propertyChange", "change").
85-
* @param callback - Callback function which will be executed when event is raised.
86-
* @param thisArg - An optional parameter which will be used as `this` context for callback execution.
87-
*/
88-
on(eventNames: string, callback: (args: EventData) => void, thisArg?: any): void;
83+
* Adds a listener for the specified event name.
84+
*
85+
* @param eventName The name of the event.
86+
* @param callback The event listener to add. Will be called when an event of
87+
* the given name is raised.
88+
* @param thisArg An optional parameter which, when set, will be bound as the
89+
* `this` context when the callback is called. Falsy values will be not be
90+
* bound.
91+
*/
92+
on(eventName: string, callback: (args: EventData) => void, thisArg?: any): void;
8993

9094
/**
9195
* Raised when the image has been downloaded.

‎packages/core/ui/list-view/index.d.ts

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -103,12 +103,16 @@ export class ListView extends View {
103103
isItemAtIndexVisible(index: number): boolean;
104104

105105
/**
106-
* A basic method signature to hook an event listener (shortcut alias to the addEventListener method).
107-
* @param eventNames - String corresponding to events (e.g. "propertyChange"). Optionally could be used more events separated by `,` (e.g. "propertyChange", "change").
108-
* @param callback - Callback function which will be executed when event is raised.
109-
* @param thisArg - An optional parameter which will be used as `this` context for callback execution.
110-
*/
111-
on(eventNames: string, callback: (data: EventData) => void, thisArg?: any): void;
106+
* Adds a listener for the specified event name.
107+
*
108+
* @param eventName The name of the event.
109+
* @param callback The event listener to add. Will be called when an event of
110+
* the given name is raised.
111+
* @param thisArg An optional parameter which, when set, will be bound as the
112+
* `this` context when the callback is called. Falsy values will be not be
113+
* bound.
114+
*/
115+
on(eventName: string, callback: (data: EventData) => void, thisArg?: any): void;
112116

113117
/**
114118
* Raised when a View for the data at the specified index should be created.

‎packages/core/ui/page/index.d.ts

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -111,12 +111,16 @@ export declare class Page extends PageBase {
111111
public accessibilityAnnouncePageEnabled: boolean;
112112

113113
/**
114-
* A basic method signature to hook an event listener (shortcut alias to the addEventListener method).
115-
* @param eventNames - String corresponding to events (e.g. "propertyChange"). Optionally could be used more events separated by `,` (e.g. "propertyChange", "change").
116-
* @param callback - Callback function which will be executed when event is raised.
117-
* @param thisArg - An optional parameter which will be used as `this` context for callback execution.
118-
*/
119-
public on(eventNames: string, callback: (data: EventData) => void, thisArg?: any): void;
114+
* Adds a listener for the specified event name.
115+
*
116+
* @param eventName The name of the event.
117+
* @param callback The event listener to add. Will be called when an event of
118+
* the given name is raised.
119+
* @param thisArg An optional parameter which, when set, will be bound as the
120+
* `this` context when the callback is called. Falsy values will be not be
121+
* bound.
122+
*/
123+
public on(eventName: string, callback: (data: EventData) => void, thisArg?: any): void;
120124

121125
/**
122126
* Raised when navigation to the page has started.

‎packages/core/ui/placeholder/index.d.ts

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -13,12 +13,16 @@ export class Placeholder extends View {
1313
public static creatingViewEvent: string;
1414

1515
/**
16-
* A basic method signature to hook an event listener (shortcut alias to the addEventListener method).
17-
* @param eventNames - String corresponding to events (e.g. "propertyChange"). Optionally could be used more events separated by `,` (e.g. "propertyChange", "change").
18-
* @param callback - Callback function which will be executed when event is raised.
19-
* @param thisArg - An optional parameter which will be used as `this` context for callback execution.
16+
* Adds a listener for the specified event name.
17+
*
18+
* @param eventName The name of the event.
19+
* @param callback The event listener to add. Will be called when an event of
20+
* the given name is raised.
21+
* @param thisArg An optional parameter which, when set, will be bound as the
22+
* `this` context when the callback is called. Falsy values will be not be
23+
* bound.
2024
*/
21-
on(eventNames: string, callback: (args: EventData) => void, thisArg?: any): void;
25+
on(eventName: string, callback: (args: EventData) => void, thisArg?: any): void;
2226

2327
/**
2428
* Raised when a creatingView event occurs.

‎packages/core/ui/scroll-view/index.d.ts

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -62,12 +62,16 @@ export class ScrollView extends ContentView {
6262
orientation: CoreTypes.OrientationType;
6363

6464
/**
65-
* A basic method signature to hook an event listener (shortcut alias to the addEventListener method).
66-
* @param eventNames - String corresponding to events (e.g. "propertyChange"). Optionally could be used more events separated by `,` (e.g. "propertyChange", "change").
67-
* @param callback - Callback function which will be executed when event is raised.
68-
* @param thisArg - An optional parameter which will be used as `this` context for callback execution.
65+
* Adds a listener for the specified event name.
66+
*
67+
* @param eventName The name of the event.
68+
* @param callback The event listener to add. Will be called when an event of
69+
* the given name is raised.
70+
* @param thisArg An optional parameter which, when set, will be bound as the
71+
* `this` context when the callback is called. Falsy values will be not be
72+
* bound.
6973
*/
70-
on(eventNames: string, callback: (data: EventData) => void, thisArg?: any): void;
74+
on(eventName: string, callback: (data: EventData) => void, thisArg?: any): void;
7175

7276
/**
7377
* Raised when a scroll event occurs.

‎packages/core/ui/search-bar/index.d.ts

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -48,12 +48,16 @@ export class SearchBar extends View {
4848
textFieldHintColor: Color;
4949

5050
/**
51-
* A basic method signature to hook an event listener (shortcut alias to the addEventListener method).
52-
* @param eventNames - String corresponding to events (e.g. "propertyChange"). Optionally could be used more events separated by `,` (e.g. "propertyChange", "change").
53-
* @param callback - Callback function which will be executed when event is raised.
54-
* @param thisArg - An optional parameter which will be used as `this` context for callback execution.
51+
* Adds a listener for the specified event name.
52+
*
53+
* @param eventName The name of the event.
54+
* @param callback The event listener to add. Will be called when an event of
55+
* the given name is raised.
56+
* @param thisArg An optional parameter which, when set, will be bound as the
57+
* `this` context when the callback is called. Falsy values will be not be
58+
* bound.
5559
*/
56-
on(eventNames: string, callback: (data: EventData) => void, thisArg?: any): void;
60+
on(eventName: string, callback: (data: EventData) => void, thisArg?: any): void;
5761

5862
/**
5963
* Raised when a search bar search is submitted.

‎packages/core/ui/segmented-bar/index.d.ts

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -60,12 +60,16 @@ export class SegmentedBar extends View implements AddChildFromBuilder, AddArrayF
6060
public static selectedIndexChangedEvent: string;
6161

6262
/**
63-
* A basic method signature to hook an event listener (shortcut alias to the addEventListener method).
64-
* @param eventNames - String corresponding to events (e.g. "propertyChange"). Optionally could be used more events separated by `,` (e.g. "propertyChange", "change").
65-
* @param callback - Callback function which will be executed when event is raised.
66-
* @param thisArg - An optional parameter which will be used as `this` context for callback execution.
63+
* Adds a listener for the specified event name.
64+
*
65+
* @param eventName The name of the event.
66+
* @param callback The event listener to add. Will be called when an event of
67+
* the given name is raised.
68+
* @param thisArg An optional parameter which, when set, will be bound as the
69+
* `this` context when the callback is called. Falsy values will be not be
70+
* bound.
6771
*/
68-
on(eventNames: string, callback: (data: EventData) => void, thisArg?: any): void;
72+
on(eventName: string, callback: (data: EventData) => void, thisArg?: any): void;
6973

7074
/**
7175
* Raised when the selected index changes.

‎packages/core/ui/tab-view/index.d.ts

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -145,12 +145,16 @@ export class TabView extends View {
145145
public static selectedIndexChangedEvent: string;
146146

147147
/**
148-
* A basic method signature to hook an event listener (shortcut alias to the addEventListener method).
149-
* @param eventNames - String corresponding to events (e.g. "propertyChange"). Optionally could be used more events separated by `,` (e.g. "propertyChange", "change").
150-
* @param callback - Callback function which will be executed when event is raised.
151-
* @param thisArg - An optional parameter which will be used as `this` context for callback execution.
152-
*/
153-
on(eventNames: string, callback: (data: EventData) => void, thisArg?: any): void;
148+
* Adds a listener for the specified event name.
149+
*
150+
* @param eventName The name of the event.
151+
* @param callback The event listener to add. Will be called when an event of
152+
* the given name is raised.
153+
* @param thisArg An optional parameter which, when set, will be bound as the
154+
* `this` context when the callback is called. Falsy values will be not be
155+
* bound.
156+
*/
157+
on(eventName: string, callback: (data: EventData) => void, thisArg?: any): void;
154158

155159
/**
156160
* Raised when the selected index changes.

0 commit comments

Comments
 (0)