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

Add docs to some functions in event.ts

Author: Tyriar

src/vs/base/common/event.ts

@@ -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,13 +63,18 @@ 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);
 	}
 
 	/**
 	 * 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 [