docs(core): update comments for on, once, addEventListener and remove…

…EventListener (#10545)

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

@@ -424,12 +424,16 @@ export class ObservableArray<T> extends Observable {
 
 export interface ObservableArray<T> {
 	/**
-	 * A basic method signature to hook an event listener (shortcut alias to the addEventListener method).
-	 * @param eventNames - String corresponding to events (e.g. "propertyChange"). Optionally could be used more events separated by `,` (e.g. "propertyChange", "change").
-	 * @param callback - Callback function which will be executed when event is raised.
-	 * @param thisArg - An optional parameter which will be used as `this` context for callback execution.
-	 */
-	on(eventNames: string, callback: (data: EventData) => void, thisArg?: any): void;
+	 * Adds a listener for the specified event name.
+	 *
+	 * @param eventName The name of the event.
+	 * @param callback The event listener to add. Will be called when an event of
+	 * the given name is raised.
+	 * @param thisArg An optional parameter which, when set, will be bound as the
+	 * `this` context when the callback is called. Falsy values will be not be
+	 * bound.
+	 */
+	on(eventName: string, callback: (data: EventData) => void, thisArg?: any): void;
 
 	on(event: 'change', callback: (args: ChangedData<T>) => void, thisArg?: any): void;
 }

packages/core/data/observable/index.ts

@@ -150,27 +150,42 @@ export class Observable {
 	}
 
 	/**
-	 * A basic method signature to hook an event listener (shortcut alias to the addEventListener method).
-	 * @param eventName Name of the event to attach to.
-	 * @param callback - Callback function which will be executed when event is raised.
-	 * @param thisArg - An optional parameter which will be used as `this` context for callback execution.
+	 * Adds a listener for the specified event name.
+	 *
+	 * @param eventName The name of the event.
+	 * @param callback The event listener to add. Will be called when an event of
+	 * the given name is raised.
+	 * @param thisArg An optional parameter which, when set, will be bound as the
+	 * `this` context when the callback is called. Falsy values will be not be
+	 * bound.
 	 */
 	public on(eventName: string, callback: (data: EventData) => void, thisArg?: any): void {
 		this.addEventListener(eventName, callback, thisArg);
 	}
 
 	/**
-	 * Adds one-time listener function for the event named `event`.
-	 * @param eventName Name of the event to attach to.
-	 * @param callback A function to be called when the specified event is raised.
-	 * @param thisArg An optional parameter which when set will be used as "this" in callback method call.
+	 * Adds a listener for the specified event name, which, once fired, will
+	 * remove itself.
+	 *
+	 * @param eventName The name of the event.
+	 * @param callback The event listener to add. Will be called when an event of
+	 * the given name is raised.
+	 * @param thisArg An optional parameter which, when set, will be bound as the
+	 * `this` context when the callback is called. Falsy values will be not be
+	 * bound.
 	 */
 	public once(eventName: string, callback: (data: EventData) => void, thisArg?: any): void {
 		this.addEventListener(eventName, callback, thisArg, true);
 	}
 
 	/**
-	 * Shortcut alias to the removeEventListener method.
+	 * Removes the listener(s) for the specified event name.
+	 *
+	 * @param eventName The name of the event.
+	 * @param callback An optional specific event listener to remove (if omitted,
+	 * all event listeners by this name will be removed).
+	 * @param thisArg An optional parameter which, when set, will be used to
+	 * refine search of the correct event listener to be removed.
 	 */
 	public off(eventName: string, callback?: (data: EventData) => void, thisArg?: any): void {
 		this.removeEventListener(eventName, callback, thisArg);

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

@@ -183,12 +183,16 @@ export class VirtualArray<T> extends Observable {
 }
 export interface VirtualArray<T> {
 	/**
-	 * A basic method signature to hook an event listener (shortcut alias to the addEventListener method).
-	 * @param eventNames - String corresponding to events (e.g. "propertyChange"). Optionally could be used more events separated by `,` (e.g. "propertyChange", "change").
-	 * @param callback - Callback function which will be executed when event is raised.
-	 * @param thisArg - An optional parameter which will be used as `this` context for callback execution.
+	 * Adds a listener for the specified event name.
+	 *
+	 * @param eventName The name of the event.
+	 * @param callback The event listener to add. Will be called when an event of
+	 * the given name is raised.
+	 * @param thisArg An optional parameter which, when set, will be bound as the
+	 * `this` context when the callback is called. Falsy values will be not be
+	 * bound.
 	 */
-	on(eventNames: string, callback: (data: EventData) => void, thisArg?: any): void;
+	on(eventName: string, callback: (data: EventData) => void, thisArg?: any): void;
 	/**
 	 * Raised when still not loaded items are requested.
 	 */

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

@@ -129,12 +129,16 @@ export class ActionItem extends ViewBase {
 	actionBar: ActionBar;
 
 	/**
-	 * A basic method signature to hook an event listener (shortcut alias to the addEventListener method).
-	 * @param eventNames - String corresponding to events (e.g. "propertyChange"). Optionally could be used more events separated by `,` (e.g. "propertyChange", "change").
-	 * @param callback - Callback function which will be executed when event is raised.
-	 * @param thisArg - An optional parameter which will be used as `this` context for callback execution.
-	 */
-	on(eventNames: string, callback: (data: EventData) => void): void;
+	 * Adds a listener for the specified event name.
+	 *
+	 * @param eventName The name of the event.
+	 * @param callback The event listener to add. Will be called when an event of
+	 * the given name is raised.
+	 * @param thisArg An optional parameter which, when set, will be bound as the
+	 * `this` context when the callback is called. Falsy values will be not be
+	 * bound.
+	 */
+	on(eventName: string, callback: (data: EventData) => void): void;
 
 	/**
 	 * Raised when a tap event occurs.

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

@@ -26,12 +26,16 @@ export class Button extends TextBase {
 	textWrap: boolean;
 
 	/**
-	 * A basic method signature to hook an event listener (shortcut alias to the addEventListener method).
-	 * @param eventNames - String corresponding to events (e.g. "propertyChange"). Optionally could be used more events separated by `,` (e.g. "propertyChange", "change").
-	 * @param callback - Callback function which will be executed when event is raised.
-	 * @param thisArg - An optional parameter which will be used as `this` context for callback execution.
+	 * Adds a listener for the specified event name.
+	 *
+	 * @param eventName The name of the event.
+	 * @param callback The event listener to add. Will be called when an event of
+	 * the given name is raised.
+	 * @param thisArg An optional parameter which, when set, will be bound as the
+	 * `this` context when the callback is called. Falsy values will be not be
+	 * bound.
 	 */
-	on(eventNames: string, callback: (data: EventData) => void, thisArg?: any): void;
+	on(eventName: string, callback: (data: EventData) => void, thisArg?: any): void;
 
 	/**
 	 * Raised when a tap event occurs.

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

@@ -590,20 +590,27 @@ export abstract class View extends ViewCommon {
 	public getGestureObservers(type: GestureTypes): Array<GesturesObserver> | undefined;
 
 	/**
-	 * Removes listener(s) for the specified event name.
-	 * @param eventNames Comma delimited names of the events or gesture types the specified listener is associated with.
-	 * @param callback An optional parameter pointing to a specific listener. If not defined, all listeners for the event names will be removed.
-	 * @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.
+	 * Removes the listener(s) for the specified event name.
+	 *
+	 * @param eventName The name of the event.
+	 * @param callback An optional specific event listener to remove (if omitted,
+	 * all event listeners by this name will be removed).
+	 * @param thisArg An optional parameter which, when set, will be used to
+	 * refine search of the correct event listener to be removed.
 	 */
-	off(eventNames: string, callback?: (args: EventData) => void, thisArg?: any);
+	off(eventName: string, callback?: (args: EventData) => void, thisArg?: any);
 
 	/**
-	 * A basic method signature to hook an event listener (shortcut alias to the addEventListener method).
-	 * @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.
-	 * @param callback - Callback function which will be executed when event is raised.
-	 * @param thisArg - An optional parameter which will be used as `this` context for callback execution.
-	 */
-	on(eventNames: string, callback: (args: EventData) => void, thisArg?: any);
+	 * Adds a listener for the specified event name.
+	 *
+	 * @param eventName The name of the event.
+	 * @param callback The event listener to add. Will be called when an event of
+	 * the given name is raised.
+	 * @param thisArg An optional parameter which, when set, will be bound as the
+	 * `this` context when the callback is called. Falsy values will be not be
+	 * bound.
+	 */
+	on(eventName: string, callback: (args: EventData) => void, thisArg?: any);
 
 	/**
 	 * Raised when a loaded event occurs.

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

@@ -225,12 +225,16 @@ export class Frame extends FrameBase {
 	//@endprivate
 
 	/**
-	 * A basic method signature to hook an event listener (shortcut alias to the addEventListener method).
-	 * @param eventNames - String corresponding to events (e.g. "propertyChange"). Optionally could be used more events separated by `,` (e.g. "propertyChange", "change").
-	 * @param callback - Callback function which will be executed when event is raised.
-	 * @param thisArg - An optional parameter which will be used as `this` context for callback execution.
-	 */
-	on(eventNames: string, callback: (args: EventData) => void, thisArg?: any): void;
+	 * Adds a listener for the specified event name.
+	 *
+	 * @param eventName The name of the event.
+	 * @param callback The event listener to add. Will be called when an event of
+	 * the given name is raised.
+	 * @param thisArg An optional parameter which, when set, will be bound as the
+	 * `this` context when the callback is called. Falsy values will be not be
+	 * bound.
+	 */
+	on(eventName: string, callback: (args: EventData) => void, thisArg?: any): void;
 
 	/**
 	 * Raised when navigation to the page has started.

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

@@ -80,12 +80,16 @@ export class Cache extends Observable {
 	clear(): void;
 
 	/**
-	 * A basic method signature to hook an event listener (shortcut alias to the addEventListener method).
-	 * @param eventNames - String corresponding to events (e.g. "propertyChange"). Optionally could be used more events separated by `,` (e.g. "propertyChange", "change").
-	 * @param callback - Callback function which will be executed when event is raised.
-	 * @param thisArg - An optional parameter which will be used as `this` context for callback execution.
-	 */
-	on(eventNames: string, callback: (args: EventData) => void, thisArg?: any): void;
+	 * Adds a listener for the specified event name.
+	 *
+	 * @param eventName The name of the event.
+	 * @param callback The event listener to add. Will be called when an event of
+	 * the given name is raised.
+	 * @param thisArg An optional parameter which, when set, will be bound as the
+	 * `this` context when the callback is called. Falsy values will be not be
+	 * bound.
+	 */
+	on(eventName: string, callback: (args: EventData) => void, thisArg?: any): void;
 
 	/**
 	 * Raised when the image has been downloaded.

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

@@ -103,12 +103,16 @@ export class ListView extends View {
 	isItemAtIndexVisible(index: number): boolean;
 
 	/**
-	 * A basic method signature to hook an event listener (shortcut alias to the addEventListener method).
-	 * @param eventNames - String corresponding to events (e.g. "propertyChange"). Optionally could be used more events separated by `,` (e.g. "propertyChange", "change").
-	 * @param callback - Callback function which will be executed when event is raised.
-	 * @param thisArg - An optional parameter which will be used as `this` context for callback execution.
-	 */
-	on(eventNames: string, callback: (data: EventData) => void, thisArg?: any): void;
+	 * Adds a listener for the specified event name.
+	 *
+	 * @param eventName The name of the event.
+	 * @param callback The event listener to add. Will be called when an event of
+	 * the given name is raised.
+	 * @param thisArg An optional parameter which, when set, will be bound as the
+	 * `this` context when the callback is called. Falsy values will be not be
+	 * bound.
+	 */
+	on(eventName: string, callback: (data: EventData) => void, thisArg?: any): void;
 
 	/**
 	 * Raised when a View for the data at the specified index should be created.

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

@@ -111,12 +111,16 @@ export declare class Page extends PageBase {
 	public accessibilityAnnouncePageEnabled: boolean;
 
 	/**
-	 * A basic method signature to hook an event listener (shortcut alias to the addEventListener method).
-	 * @param eventNames - String corresponding to events (e.g. "propertyChange"). Optionally could be used more events separated by `,` (e.g. "propertyChange", "change").
-	 * @param callback - Callback function which will be executed when event is raised.
-	 * @param thisArg - An optional parameter which will be used as `this` context for callback execution.
-	 */
-	public on(eventNames: string, callback: (data: EventData) => void, thisArg?: any): void;
+	 * Adds a listener for the specified event name.
+	 *
+	 * @param eventName The name of the event.
+	 * @param callback The event listener to add. Will be called when an event of
+	 * the given name is raised.
+	 * @param thisArg An optional parameter which, when set, will be bound as the
+	 * `this` context when the callback is called. Falsy values will be not be
+	 * bound.
+	 */
+	public on(eventName: string, callback: (data: EventData) => void, thisArg?: any): void;
 
 	/**
 	 * Raised when navigation to the page has started.

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

@@ -13,12 +13,16 @@ export class Placeholder extends View {
 	public static creatingViewEvent: string;
 
 	/**
-	 * A basic method signature to hook an event listener (shortcut alias to the addEventListener method).
-	 * @param eventNames - String corresponding to events (e.g. "propertyChange"). Optionally could be used more events separated by `,` (e.g. "propertyChange", "change").
-	 * @param callback - Callback function which will be executed when event is raised.
-	 * @param thisArg - An optional parameter which will be used as `this` context for callback execution.
+	 * Adds a listener for the specified event name.
+	 *
+	 * @param eventName The name of the event.
+	 * @param callback The event listener to add. Will be called when an event of
+	 * the given name is raised.
+	 * @param thisArg An optional parameter which, when set, will be bound as the
+	 * `this` context when the callback is called. Falsy values will be not be
+	 * bound.
 	 */
-	on(eventNames: string, callback: (args: EventData) => void, thisArg?: any): void;
+	on(eventName: string, callback: (args: EventData) => void, thisArg?: any): void;
 
 	/**
 	 * Raised when a creatingView event occurs.

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

@@ -62,12 +62,16 @@ export class ScrollView extends ContentView {
 	orientation: CoreTypes.OrientationType;
 
 	/**
-	 * A basic method signature to hook an event listener (shortcut alias to the addEventListener method).
-	 * @param eventNames - String corresponding to events (e.g. "propertyChange"). Optionally could be used more events separated by `,` (e.g. "propertyChange", "change").
-	 * @param callback - Callback function which will be executed when event is raised.
-	 * @param thisArg - An optional parameter which will be used as `this` context for callback execution.
+	 * Adds a listener for the specified event name.
+	 *
+	 * @param eventName The name of the event.
+	 * @param callback The event listener to add. Will be called when an event of
+	 * the given name is raised.
+	 * @param thisArg An optional parameter which, when set, will be bound as the
+	 * `this` context when the callback is called. Falsy values will be not be
+	 * bound.
 	 */
-	on(eventNames: string, callback: (data: EventData) => void, thisArg?: any): void;
+	on(eventName: string, callback: (data: EventData) => void, thisArg?: any): void;
 
 	/**
 	 * Raised when a scroll event occurs.

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

@@ -48,12 +48,16 @@ export class SearchBar extends View {
 	textFieldHintColor: Color;
 
 	/**
-	 * A basic method signature to hook an event listener (shortcut alias to the addEventListener method).
-	 * @param eventNames - String corresponding to events (e.g. "propertyChange"). Optionally could be used more events separated by `,` (e.g. "propertyChange", "change").
-	 * @param callback - Callback function which will be executed when event is raised.
-	 * @param thisArg - An optional parameter which will be used as `this` context for callback execution.
+	 * Adds a listener for the specified event name.
+	 *
+	 * @param eventName The name of the event.
+	 * @param callback The event listener to add. Will be called when an event of
+	 * the given name is raised.
+	 * @param thisArg An optional parameter which, when set, will be bound as the
+	 * `this` context when the callback is called. Falsy values will be not be
+	 * bound.
 	 */
-	on(eventNames: string, callback: (data: EventData) => void, thisArg?: any): void;
+	on(eventName: string, callback: (data: EventData) => void, thisArg?: any): void;
 
 	/**
 	 * Raised when a search bar search is submitted.

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

@@ -60,12 +60,16 @@ export class SegmentedBar extends View implements AddChildFromBuilder, AddArrayF
 	public static selectedIndexChangedEvent: string;
 
 	/**
-	 * A basic method signature to hook an event listener (shortcut alias to the addEventListener method).
-	 * @param eventNames - String corresponding to events (e.g. "propertyChange"). Optionally could be used more events separated by `,` (e.g. "propertyChange", "change").
-	 * @param callback - Callback function which will be executed when event is raised.
-	 * @param thisArg - An optional parameter which will be used as `this` context for callback execution.
+	 * Adds a listener for the specified event name.
+	 *
+	 * @param eventName The name of the event.
+	 * @param callback The event listener to add. Will be called when an event of
+	 * the given name is raised.
+	 * @param thisArg An optional parameter which, when set, will be bound as the
+	 * `this` context when the callback is called. Falsy values will be not be
+	 * bound.
 	 */
-	on(eventNames: string, callback: (data: EventData) => void, thisArg?: any): void;
+	on(eventName: string, callback: (data: EventData) => void, thisArg?: any): void;
 
 	/**
 	 * Raised when the selected index changes.

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

@@ -145,12 +145,16 @@ export class TabView extends View {
 	public static selectedIndexChangedEvent: string;
 
 	/**
-	 * A basic method signature to hook an event listener (shortcut alias to the addEventListener method).
-	 * @param eventNames - String corresponding to events (e.g. "propertyChange"). Optionally could be used more events separated by `,` (e.g. "propertyChange", "change").
-	 * @param callback - Callback function which will be executed when event is raised.
-	 * @param thisArg - An optional parameter which will be used as `this` context for callback execution.
-	 */
-	on(eventNames: string, callback: (data: EventData) => void, thisArg?: any): void;
+	 * Adds a listener for the specified event name.
+	 *
+	 * @param eventName The name of the event.
+	 * @param callback The event listener to add. Will be called when an event of
+	 * the given name is raised.
+	 * @param thisArg An optional parameter which, when set, will be bound as the
+	 * `this` context when the callback is called. Falsy values will be not be
+	 * bound.
+	 */
+	on(eventName: string, callback: (data: EventData) => void, thisArg?: any): void;
 
 	/**
 	 * Raised when the selected index changes.