mirror of
https://github.com/Microsoft/vscode
synced 2024-08-28 13:29:44 +00:00
Merge pull request #167074 from microsoft/tyriar/163572_1
Add docs to some functions in event.ts
This commit is contained in:
commit
334b6014e7
|
@ -27,8 +27,7 @@ const _enableSnapshotPotentialLeakWarning = false;
|
|||
// _enableSnapshotPotentialLeakWarning = Boolean("TRUE"); // causes a linter warning so that it cannot be pushed
|
||||
|
||||
/**
|
||||
* To an event a function with one or zero parameters
|
||||
* can be subscribed. The event is the subscriber function itself.
|
||||
* An event with zero or one parameters that can be subscribed to. The event is a function itself.
|
||||
*/
|
||||
export interface Event<T> {
|
||||
(listener: (e: T) => any, thisArgs?: any, disposables?: IDisposable[] | DisposableStore): IDisposable;
|
||||
|
@ -37,7 +36,6 @@ export interface Event<T> {
|
|||
export namespace Event {
|
||||
export const None: Event<any> = () => Disposable.None;
|
||||
|
||||
|
||||
function _addLeakageTraceLogic(options: EmitterOptions) {
|
||||
if (_enableSnapshotPotentialLeakWarning) {
|
||||
const { onDidAddListener: origListenerDidAdd } = options;
|
||||
|
@ -65,6 +63,9 @@ export namespace Event {
|
|||
* *NOTE* that this function returns an `Event` and it MUST be called with a `DisposableStore` whenever the returned
|
||||
* event is accessible to "third parties", e.g the event is a public property. Otherwise a leaked listener on the
|
||||
* returned event causes this utility to leak a listener on the original event.
|
||||
*
|
||||
* @param event The event source for the new event.
|
||||
* @param disposable A disposable store to add the new EventEmitter to.
|
||||
*/
|
||||
export function defer(event: Event<unknown>, disposable?: DisposableStore): Event<void> {
|
||||
return debounce<unknown, void>(event, () => void 0, 0, undefined, undefined, disposable);
|
||||
|
@ -72,6 +73,8 @@ export namespace Event {
|
|||
|
||||
/**
|
||||
* Given an event, returns another event which only fires once.
|
||||
*
|
||||
* @param event The event source for the new event.
|
||||
*/
|
||||
export function once<T>(event: Event<T>): Event<T> {
|
||||
return (listener, thisArgs = null, disposables?) => {
|
||||
|
@ -99,9 +102,16 @@ export namespace Event {
|
|||
}
|
||||
|
||||
/**
|
||||
* Maps an event of one type into an event of another type using a mapping function, similar to how
|
||||
* `Array.prototype.map` works.
|
||||
*
|
||||
* *NOTE* that this function returns an `Event` and it MUST be called with a `DisposableStore` whenever the returned
|
||||
* event is accessible to "third parties", e.g the event is a public property. Otherwise a leaked listener on the
|
||||
* returned event causes this utility to leak a listener on the original event.
|
||||
*
|
||||
* @param event The event source for the new event.
|
||||
* @param map The mapping function.
|
||||
* @param disposable A disposable store to add the new EventEmitter to.
|
||||
*/
|
||||
export function map<I, O>(event: Event<I>, map: (i: I) => O, disposable?: DisposableStore): Event<O> {
|
||||
return snapshot((listener, thisArgs = null, disposables?) => event(i => listener.call(thisArgs, map(i)), null, disposables), disposable);
|
||||
|
@ -278,9 +288,21 @@ export namespace Event {
|
|||
}
|
||||
|
||||
/**
|
||||
* Splits an event whose parameter is a union type into 2 separate events for each type in the union.
|
||||
*
|
||||
* *NOTE* that this function returns an `Event` and it MUST be called with a `DisposableStore` whenever the returned
|
||||
* event is accessible to "third parties", e.g the event is a public property. Otherwise a leaked listener on the
|
||||
* returned event causes this utility to leak a listener on the original event.
|
||||
*
|
||||
* @example
|
||||
* ```
|
||||
* const event = new EventEmitter<number | undefined>().event;
|
||||
* const [numberEvent, undefinedEvent] = Event.split(event, isUndefined);
|
||||
* ```
|
||||
*
|
||||
* @param event The event source for the new event.
|
||||
* @param isT A function that determines what event is of the first type.
|
||||
* @param disposable A disposable store to add the new EventEmitter to.
|
||||
*/
|
||||
export function split<T, U>(event: Event<T | U>, isT: (e: T | U) => e is T, disposable?: DisposableStore): [Event<T>, Event<U>] {
|
||||
return [
|
||||
|
|
Loading…
Reference in a new issue