development/vscode
development/vscode
1
0
Fork 0
mirror of https://github.com/Microsoft/vscode synced 2024-08-28 13:29:44 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #167074 from microsoft/tyriar/163572_1

Browse source 
Add docs to some functions in event.ts
This commit is contained in:
Daniel Imms 2022-11-23 09:42:36 -08:00 committed by GitHub
parent 34e5fb1b17 d3022a6dc6
commit 334b6014e7
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 25 additions and 3 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

28
src/vs/base/common/event.ts
View file

@ -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 [