@codingame/monaco-vscode-api 20.1.1 → 20.2.1

package/vscode/src/vs/base/common/observableInternal/base.d.ts

@@ -1,40 +1,168 @@
 import { DisposableStore } from "./commonFacade/deps.js";
+/**
+ * Represents an observable value.
+ *
+ * @template T The type of the values the observable can hold.
+ */
 export interface IObservable<T> extends IObservableWithChange<T, unknown> {
 }
+/**
+ * Represents an observable value.
+ *
+ * @template T The type of the values the observable can hold.
+ * @template TChange The type used to describe value changes
+ * (usually `void` and only used in advanced scenarios).
+ * While observers can miss temporary values of an observable,
+ * they will receive all change values (as long as they are subscribed)!
+ */
 export interface IObservableWithChange<T, TChange = unknown> {
+    /**
+     * Returns the current value.
+     *
+     * Calls {@link IObserver.handleChange} if the observable notices that the value changed.
+     * Must not be called from {@link IObserver.handleChange}!
+     */
     get(): T;
+    /**
+     * Forces the observable to check for changes and report them.
+     *
+     * Has the same effect as calling {@link IObservable.get}, but does not force the observable
+     * to actually construct the value, e.g. if change deltas are used.
+     * Calls {@link IObserver.handleChange} if the observable notices that the value changed.
+     * Must not be called from {@link IObserver.handleChange}!
+     */
     reportChanges(): void;
+    /**
+     * Adds the observer to the set of subscribed observers.
+     * This method is idempotent.
+     */
     addObserver(observer: IObserver): void;
+    /**
+     * Removes the observer from the set of subscribed observers.
+     * This method is idempotent.
+     */
     removeObserver(observer: IObserver): void;
+    /**
+     * Reads the current value and subscribes the reader to this observable.
+     *
+     * Calls {@link IReader.readObservable} if a reader is given, otherwise {@link IObservable.get}
+     * (see {@link ConvenientObservable.read} for the implementation).
+     */
     read(reader: IReader | undefined): T;
+    /**
+     * Makes sure this value is computed eagerly.
+     */
     recomputeInitiallyAndOnChange(store: DisposableStore, handleValue?: (value: T) => void): IObservable<T>;
+    /**
+     * Makes sure this value is cached.
+     */
     keepObserved(store: DisposableStore): IObservable<T>;
+    /**
+     * Creates a derived observable that depends on this observable.
+     * Use the reader to read other observables
+     * (see {@link ConvenientObservable.map} for the implementation).
+     */
     map<TNew>(fn: (value: T, reader: IReader) => TNew): IObservable<TNew>;
     map<TNew>(owner: object, fn: (value: T, reader: IReader) => TNew): IObservable<TNew>;
     flatten<TNew>(this: IObservable<IObservable<TNew>>): IObservable<TNew>;
+    /**
+     * ONLY FOR DEBUGGING!
+     * Logs computations of this derived.
+    */
     log(): IObservableWithChange<T, TChange>;
+    /**
+     * A human-readable name for debugging purposes.
+     */
     readonly debugName: string;
+    /**
+     * This property captures the type of the change object. Do not use it at runtime!
+     */
     readonly TChange: TChange;
 }
+/**
+ * Represents an observer that can be subscribed to an observable.
+ *
+ * If an observer is subscribed to an observable and that observable didn't signal
+ * a change through one of the observer methods, the observer can assume that the
+ * observable didn't change.
+ * If an observable reported a possible change, {@link IObservable.reportChanges} forces
+ * the observable to report an actual change if there was one.
+ */
 export interface IObserver {
+    /**
+     * Signals that the given observable might have changed and a transaction potentially modifying that observable started.
+     * Before the given observable can call this method again, is must call {@link IObserver.endUpdate}.
+     *
+     * Implementations must not get/read the value of other observables, as they might not have received this event yet!
+     * The method {@link IObservable.reportChanges} can be used to force the observable to report the changes.
+     */
     beginUpdate<T>(observable: IObservable<T>): void;
+    /**
+     * Signals that the transaction that potentially modified the given observable ended.
+     * This is a good place to react to (potential) changes.
+     */
     endUpdate<T>(observable: IObservable<T>): void;
+    /**
+     * Signals that the given observable might have changed.
+     * The method {@link IObservable.reportChanges} can be used to force the observable to report the changes.
+     *
+     * Implementations must not get/read the value of other observables, as they might not have received this event yet!
+     * The change should be processed lazily or in {@link IObserver.endUpdate}.
+     */
     handlePossibleChange<T>(observable: IObservable<T>): void;
+    /**
+     * Signals that the given {@link observable} changed.
+     *
+     * Implementations must not get/read the value of other observables, as they might not have received this event yet!
+     * The change should be processed lazily or in {@link IObserver.endUpdate}.
+     *
+     * @param change Indicates how or why the value changed.
+     */
     handleChange<T, TChange>(observable: IObservableWithChange<T, TChange>, change: TChange): void;
 }
 export interface IReader {
+    /**
+     * Reads the value of an observable and subscribes to it.
+     */
     readObservable<T>(observable: IObservableWithChange<T, any>): T;
 }
 export interface ISettable<T, TChange = void> {
+    /**
+     * Sets the value of the observable.
+     * Use a transaction to batch multiple changes (with a transaction, observers only react at the end of the transaction).
+     *
+     * @param transaction When given, value changes are handled on demand or when the transaction ends.
+     * @param change Describes how or why the value changed.
+     */
     set(value: T, transaction: ITransaction | undefined, change: TChange): void;
 }
 export interface ITransaction {
+    /**
+     * Calls {@link Observer.beginUpdate} immediately
+     * and {@link Observer.endUpdate} when the transaction ends.
+     */
     updateObserver(observer: IObserver, observable: IObservableWithChange<any, any>): void;
 }
+/**
+ * This function is used to indicate that the caller recovered from an error that indicates a bug.
+*/
 export declare function handleBugIndicatingErrorRecovery(message: string): void;
+/**
+ * A settable observable.
+ */
 export interface ISettableObservable<T, TChange = void> extends IObservableWithChange<T, TChange>, ISettable<T, TChange> {
 }
 export interface IReaderWithStore extends IReader {
+    /**
+     * Items in this store get disposed just before the observable recomputes/reruns or when it becomes unobserved.
+    */
     get store(): DisposableStore;
+    /**
+     * Items in this store get disposed just after the observable recomputes/reruns or when it becomes unobserved.
+     * This is important if the current run needs the undisposed result from the last run.
+     *
+     * Warning: Items in this store might still get disposed before dependents (that read the now disposed value in the past) are recomputed with the new (undisposed) value!
+     * A clean solution for this is ref counting.
+    */
     get delayedStore(): DisposableStore;
 }

package/vscode/src/vs/base/common/observableInternal/changeTracker.d.ts

@@ -7,10 +7,17 @@ export interface IChangeTracker<TChangeSummary> {
 export interface IChangeContext {
     readonly changedObservable: IObservableWithChange<any, any>;
     readonly change: unknown;
+    /**
+     * Returns if the given observable caused the change.
+     */
     didChange<T, TChange>(observable: IObservableWithChange<T, TChange>): this is {
         change: TChange;
     };
 }
+/**
+ * Subscribes to and records changes and the last value of the given observables.
+ * Don't use the key "changes", as it is reserved for the changes array!
+*/
 export declare function recordChanges<TObs extends Record<any, IObservableWithChange<any, any>>>(obs: TObs): IChangeTracker<{
     [TKey in keyof TObs]: ReturnType<TObs[TKey]["get"]>;
 } & {
@@ -21,6 +28,10 @@ export declare function recordChanges<TObs extends Record<any, IObservableWithCh
         };
     }[keyof TObs])[];
 }>;
+/**
+ * Subscribes to and records changes and the last value of the given observables.
+ * Don't use the key "changes", as it is reserved for the changes array!
+*/
 export declare function recordChangesLazy<TObs extends Record<any, IObservableWithChange<any, any>>>(getObs: () => TObs): IChangeTracker<{
     [TKey in keyof TObs]: ReturnType<TObs[TKey]["get"]>;
 } & {

package/vscode/src/vs/base/common/observableInternal/debugName.d.ts

@@ -1,6 +1,18 @@
 export interface IDebugNameData {
+    /**
+     * The owner object of an observable.
+     * Used for debugging only, such as computing a name for the observable by iterating over the fields of the owner.
+     */
     readonly owner?: DebugOwner | undefined;
+    /**
+     * A string or function that returns a string that represents the name of the observable.
+     * Used for debugging only.
+     */
     readonly debugName?: DebugNameSource | undefined;
+    /**
+     * A function that points to the defining function of the object.
+     * Used for debugging only.
+     */
     readonly debugReferenceFn?: Function | undefined;
 }
 export declare class DebugNameData {
@@ -10,6 +22,10 @@ export declare class DebugNameData {
     constructor(owner: DebugOwner | undefined, debugNameSource: DebugNameSource | undefined, referenceFn: Function | undefined);
     getDebugName(target: object): string | undefined;
 }
+/**
+ * The owning object of an observable.
+ * Is only used for debugging purposes, such as computing a name for the observable by iterating over the fields of the owner.
+ */
 export type DebugOwner = object | undefined;
 export type DebugNameSource = string | (() => string | undefined);
 export declare function getDebugName(target: object, data: DebugNameData): string | undefined;

package/vscode/src/vs/base/common/observableInternal/experimental/reducer.d.ts

@@ -4,13 +4,34 @@ import { IChangeTracker } from "../changeTracker.js";
 import { DebugOwner } from "../debugName.js";
 import { IDerivedReader } from "../observables/derivedImpl.js";
 export interface IReducerOptions<T, TChangeSummary = void, TOutChange = void> {
+    /**
+     * Is called to create the initial value of the observable when it becomes observed.
+    */
     initial: T | (() => T);
+    /**
+     * Is called to dispose the observable value when it is no longer observed.
+    */
     disposeFinal?(value: T): void;
     changeTracker?: IChangeTracker<TChangeSummary>;
     equalityComparer?: EqualityComparer<T>;
+    /**
+     * Applies the changes to the value.
+     * Use `reader.reportChange` to report change details or to report a change if the same value is returned.
+    */
     update(reader: IDerivedReader<TOutChange>, previousValue: T, changes: TChangeSummary): T;
 }
+/**
+ * Creates an observable value that is based on values and changes from other observables.
+ * Additionally, a reducer can report how that state changed.
+*/
 export declare function observableReducer<T, TInChanges, TOutChange = void>(owner: DebugOwner, options: IReducerOptions<T, TInChanges, TOutChange>): SimplifyObservableWithChange<T, TOutChange>;
+/**
+ * Creates an observable value that is based on values and changes from other observables.
+ * Additionally, a reducer can report how that state changed.
+*/
 export declare function observableReducerSettable<T, TInChanges, TOutChange = void>(owner: DebugOwner, options: IReducerOptions<T, TInChanges, TOutChange>): ISettableObservable<T, TOutChange>;
+/**
+ * Returns IObservable<T> if TChange is void, otherwise IObservableWithChange<T, TChange>
+*/
 type SimplifyObservableWithChange<T, TChange> = TChange extends void ? IObservable<T> : IObservableWithChange<T, TChange>;
 export {};

package/vscode/src/vs/base/common/observableInternal/experimental/utils.d.ts

@@ -1,4 +1,15 @@
 import { IObservable, IReader } from "../base.js";
 import { DebugOwner } from "../debugName.js";
+/**
+ * Creates an observable that has the latest changed value of the given observables.
+ * Initially (and when not observed), it has the value of the last observable.
+ * When observed and any of the observables change, it has the value of the last changed observable.
+ * If multiple observables change in the same transaction, the last observable wins.
+*/
 export declare function latestChangedValue<T extends IObservable<any>[]>(owner: DebugOwner, observables: T): IObservable<ReturnType<T[number]["get"]>>;
+/**
+ * Works like a derived.
+ * However, if the value is not undefined, it is cached and will not be recomputed anymore.
+ * In that case, the derived will unsubscribe from its dependencies.
+*/
 export declare function derivedConstOnceDefined<T>(owner: DebugOwner, fn: (reader: IReader) => T): IObservable<T | undefined>;

package/vscode/src/vs/base/common/observableInternal/observables/baseObservable.d.ts

@@ -4,6 +4,10 @@ import { DebugOwner } from "../debugName.js";
 import type { keepObserved, recomputeInitiallyAndOnChange } from "../utils/utils.js";
 import { derivedOpts } from "./derived.js";
 declare let _derived: typeof derivedOpts;
+/**
+ * @internal
+ * This is to allow splitting files.
+*/
 export declare function _setDerivedOpts(derived: typeof _derived): void;
 declare let _recomputeInitiallyAndOnChange: typeof recomputeInitiallyAndOnChange;
 export declare function _setRecomputeInitiallyAndOnChange(recomputeInitiallyAndOnChange: typeof _recomputeInitiallyAndOnChange): void;
@@ -15,12 +19,23 @@ export declare abstract class ConvenientObservable<T, TChange> implements IObser
     reportChanges(): void;
     abstract addObserver(observer: IObserver): void;
     abstract removeObserver(observer: IObserver): void;
+    /** @sealed */
     read(reader: IReader | undefined): T;
+    /** @sealed */
     map<TNew>(fn: (value: T, reader: IReader) => TNew): IObservable<TNew>;
     map<TNew>(owner: DebugOwner, fn: (value: T, reader: IReader) => TNew): IObservable<TNew>;
     abstract log(): IObservableWithChange<T, TChange>;
+    /**
+     * @sealed
+     * Converts an observable of an observable value into a direct observable of the value.
+    */
     flatten<TNew>(this: IObservable<IObservableWithChange<TNew, any>>): IObservable<TNew>;
     recomputeInitiallyAndOnChange(store: DisposableStore, handleValue?: (value: T) => void): IObservable<T>;
+    /**
+     * Ensures that this observable is observed. This keeps the cache alive.
+     * However, in case of deriveds, it does not force eager evaluation (only when the value is read/get).
+     * Use `recomputeInitiallyAndOnChange` for eager evaluation.
+     */
     keepObserved(store: DisposableStore): IObservable<T>;
     abstract get debugName(): string;
     protected get debugValue(): T;

package/vscode/src/vs/base/common/observableInternal/observables/constObservable.d.ts

@@ -1,2 +1,5 @@
 import { IObservable } from "../base.js";
+/**
+ * Represents an efficient observable whose value never changes.
+ */
 export declare function constObservable<T>(value: T): IObservable<T>;

package/vscode/src/vs/base/common/observableInternal/observables/derived.d.ts

@@ -3,6 +3,12 @@ import { IChangeTracker } from "../changeTracker.js";
 import { DisposableStore, EqualityComparer, IDisposable } from "../commonFacade/deps.js";
 import { DebugOwner, IDebugNameData } from "../debugName.js";
 import { IDerivedReader } from "./derivedImpl.js";
+/**
+ * Creates an observable that is derived from other observables.
+ * The value is only recomputed when absolutely needed.
+ *
+ * {@link computeFn} should start with a JS Doc using `@description` to name the derived.
+ */
 export declare function derived<T, TChange = void>(computeFn: (reader: IDerivedReader<TChange>) => T): IObservableWithChange<T, TChange>;
 export declare function derived<T, TChange = void>(owner: DebugOwner, computeFn: (reader: IDerivedReader<TChange>) => T): IObservableWithChange<T, TChange>;
 export declare function derivedWithSetter<T>(owner: DebugOwner | undefined, computeFn: (reader: IReader) => T, setter: (value: T, transaction: ITransaction | undefined) => void): ISettableObservable<T>;
@@ -10,11 +16,30 @@ export declare function derivedOpts<T>(options: IDebugNameData & {
     equalsFn?: EqualityComparer<T>;
     onLastObserverRemoved?: (() => void);
 }, computeFn: (reader: IReader) => T): IObservable<T>;
+/**
+ * Represents an observable that is derived from other observables.
+ * The value is only recomputed when absolutely needed.
+ *
+ * {@link computeFn} should start with a JS Doc using `@description` to name the derived.
+ *
+ * Use `createEmptyChangeSummary` to create a "change summary" that can collect the changes.
+ * Use `handleChange` to add a reported change to the change summary.
+ * The compute function is given the last change summary.
+ * The change summary is discarded after the compute function was called.
+ *
+ * @see derived
+ */
 export declare function derivedHandleChanges<T, TDelta, TChangeSummary>(options: IDebugNameData & {
     changeTracker: IChangeTracker<TChangeSummary>;
     equalityComparer?: EqualityComparer<T>;
 }, computeFn: (reader: IDerivedReader<TDelta>, changeSummary: TChangeSummary) => T): IObservableWithChange<T, TDelta>;
+/**
+ * @deprecated Use `derived(reader => { reader.store.add(...) })` instead!
+*/
 export declare function derivedWithStore<T>(computeFn: (reader: IReader, store: DisposableStore) => T): IObservable<T>;
+/**
+ * @deprecated Use `derived(reader => { reader.store.add(...) })` instead!
+*/
 export declare function derivedWithStore<T>(owner: DebugOwner, computeFn: (reader: IReader, store: DisposableStore) => T): IObservable<T>;
 export declare function derivedDisposable<T extends IDisposable | undefined>(computeFn: (reader: IReader) => T): IObservable<T>;
 export declare function derivedDisposable<T extends IDisposable | undefined>(owner: DebugOwner, computeFn: (reader: IReader) => T): IObservable<T>;

package/vscode/src/vs/base/common/observableInternal/observables/derivedImpl.d.ts

@@ -4,12 +4,27 @@ import { DebugNameData } from "../debugName.js";
 import { DisposableStore, EqualityComparer } from "../commonFacade/deps.js";
 import { IChangeTracker } from "../changeTracker.js";
 export interface IDerivedReader<TChange = void> extends IReaderWithStore {
+    /**
+     * Call this to report a change delta or to force report a change, even if the new value is the same as the old value.
+    */
     reportChange(change: TChange): void;
 }
 export declare enum DerivedState {
+    /** Initial state, no previous value, recomputation needed */
     initial = 0,
+    /**
+     * A dependency could have changed.
+     * We need to explicitly ask them if at least one dependency changed.
+     */
     dependenciesMightHaveChanged = 1,
+    /**
+     * A dependency changed and we need to recompute.
+     * After recomputation, we need to check the previous value to see if we changed as well.
+     */
     stale = 2,
+    /**
+     * No change reported, our cached value is up to date.
+     */
     upToDate = 3
 }
 export declare class Derived<T, TChangeSummary = any, TChange = void> extends BaseObservable<T, TChange> implements IDerivedReader<TChange>, IObserver {

package/vscode/src/vs/base/common/observableInternal/observables/lazyObservableValue.d.ts

@@ -2,6 +2,9 @@ import { EqualityComparer } from "../commonFacade/deps.js";
 import { IObserver, ISettableObservable, ITransaction } from "../base.js";
 import { DebugNameData } from "../debugName.js";
 import { BaseObservable } from "./baseObservable.js";
+/**
+ * Holds off updating observers until the value is actually read.
+*/
 export declare class LazyObservableValue<T, TChange = void> extends BaseObservable<T, TChange> implements ISettableObservable<T, TChange> {
     private readonly _debugNameData;
     private readonly _equalityComparator;

package/vscode/src/vs/base/common/observableInternal/observables/observableSignal.d.ts

@@ -1,4 +1,9 @@
 import { IObservableWithChange, ITransaction } from "../base.js";
+/**
+ * Creates a signal that can be triggered to invalidate observers.
+ * Signals don't have a value - when they are triggered they indicate a change.
+ * However, signals can carry a delta that is passed to observers.
+ */
 export declare function observableSignal<TDelta = void>(debugName: string): IObservableSignal<TDelta>;
 export declare function observableSignal<TDelta = void>(owner: object): IObservableSignal<TDelta>;
 export interface IObservableSignal<TChange> extends IObservableWithChange<void, TChange> {

package/vscode/src/vs/base/common/observableInternal/observables/observableValue.d.ts

@@ -2,6 +2,12 @@ import { ISettableObservable, ITransaction } from "../base.js";
 import { BaseObservable } from "./baseObservable.js";
 import { EqualityComparer, IDisposable } from "../commonFacade/deps.js";
 import { DebugNameData } from "../debugName.js";
+/**
+ * Creates an observable value.
+ * Observers get informed when the value changes.
+ * @template TChange An arbitrary type to describe how or why the value changed. Defaults to `void`.
+ * Observers will receive every single change value.
+ */
 export declare function observableValue<T, TChange = void>(name: string, initialValue: T): ISettableObservable<T, TChange>;
 export declare function observableValue<T, TChange = void>(owner: object, initialValue: T): ISettableObservable<T, TChange>;
 export declare class ObservableValue<T, TChange = void> extends BaseObservable<T, TChange> implements ISettableObservable<T, TChange> {
@@ -19,6 +25,10 @@ export declare class ObservableValue<T, TChange = void> extends BaseObservable<T
     };
     debugSetValue(value: unknown): void;
 }
+/**
+ * A disposable observable. When disposed, its value is also disposed.
+ * When a new value is set, the previous value is disposed.
+ */
 export declare function disposableObservableValue<T extends IDisposable | undefined, TChange = void>(nameOrOwner: string | object, initialValue: T): ISettableObservable<T, TChange> & IDisposable;
 export declare class DisposableObservableValue<T extends IDisposable | undefined, TChange = void> extends ObservableValue<T, TChange> implements IDisposable {
     protected _setValue(newValue: T): void;

package/vscode/src/vs/base/common/observableInternal/reactions/autorun.d.ts

@@ -2,14 +2,41 @@ import { IReaderWithStore, IReader, IObservable } from "../base.js";
 import { IChangeTracker } from "../changeTracker.js";
 import { DisposableStore, IDisposable } from "../commonFacade/deps.js";
 import { IDebugNameData } from "../debugName.js";
+/**
+ * Runs immediately and whenever a transaction ends and an observed observable changed.
+ * {@link fn} should start with a JS Doc using `@description` to name the autorun.
+ */
 export declare function autorun(fn: (reader: IReaderWithStore) => void): IDisposable;
+/**
+ * Runs immediately and whenever a transaction ends and an observed observable changed.
+ * {@link fn} should start with a JS Doc using `@description` to name the autorun.
+ */
 export declare function autorunOpts(options: IDebugNameData & {}, fn: (reader: IReaderWithStore) => void): IDisposable;
+/**
+ * Runs immediately and whenever a transaction ends and an observed observable changed.
+ * {@link fn} should start with a JS Doc using `@description` to name the autorun.
+ *
+ * Use `changeTracker.createChangeSummary` to create a "change summary" that can collect the changes.
+ * Use `changeTracker.handleChange` to add a reported change to the change summary.
+ * The run function is given the last change summary.
+ * The change summary is discarded after the run function was called.
+ *
+ * @see autorun
+ */
 export declare function autorunHandleChanges<TChangeSummary>(options: IDebugNameData & {
     changeTracker: IChangeTracker<TChangeSummary>;
 }, fn: (reader: IReader, changeSummary: TChangeSummary) => void): IDisposable;
+/**
+ * @see autorunHandleChanges (but with a disposable store that is cleared before the next run or on dispose)
+ */
 export declare function autorunWithStoreHandleChanges<TChangeSummary>(options: IDebugNameData & {
     changeTracker: IChangeTracker<TChangeSummary>;
 }, fn: (reader: IReader, changeSummary: TChangeSummary, store: DisposableStore) => void): IDisposable;
+/**
+ * @see autorun (but with a disposable store that is cleared before the next run or on dispose)
+ *
+ * @deprecated Use `autorun(reader => { reader.store.add(...) })` instead!
+ */
 export declare function autorunWithStore(fn: (reader: IReader, store: DisposableStore) => void): IDisposable;
 export declare function autorunDelta<T>(observable: IObservable<T>, handler: (args: {
     lastValue: T | undefined;

package/vscode/src/vs/base/common/observableInternal/reactions/autorunImpl.d.ts

@@ -3,7 +3,14 @@ import { DebugNameData } from "../debugName.js";
 import { DisposableStore, IDisposable } from "../commonFacade/deps.js";
 import { IChangeTracker } from "../changeTracker.js";
 export declare enum AutorunState {
+    /**
+     * A dependency could have changed.
+     * We need to explicitly ask them if at least one dependency changed.
+     */
     dependenciesMightHaveChanged = 1,
+    /**
+     * A dependency changed and we need to recompute.
+     */
     stale = 2,
     upToDate = 3
 }

package/vscode/src/vs/base/common/observableInternal/transaction.d.ts

@@ -1,7 +1,16 @@
 import { IObservable, IObserver, ITransaction } from "./base.js";
+/**
+ * Starts a transaction in which many observables can be changed at once.
+ * {@link fn} should start with a JS Doc using `@description` to give the transaction a debug name.
+ * Reaction run on demand or when the transaction ends.
+ */
 export declare function transaction(fn: (tx: ITransaction) => void, getDebugName?: () => string): void;
 export declare function globalTransaction(fn: (tx: ITransaction) => void): void;
+/** @deprecated */
 export declare function asyncTransaction(fn: (tx: ITransaction) => Promise<void>, getDebugName?: () => string): Promise<void>;
+/**
+ * Allows to chain transactions.
+ */
 export declare function subtransaction(tx: ITransaction | undefined, fn: (tx: ITransaction) => void, getDebugName?: () => string): void;
 export declare class TransactionImpl implements ITransaction {
     readonly _fn: Function;

package/vscode/src/vs/base/common/observableInternal/utils/promise.d.ts

@@ -2,27 +2,73 @@ import { IObservable } from "../base.js";
 export declare class ObservableLazy<T> {
     private readonly _computeValue;
     private readonly _value;
+    /**
+     * The cached value.
+     * Does not force a computation of the value.
+     */
     get cachedValue(): IObservable<T | undefined>;
     constructor(_computeValue: () => T);
+    /**
+     * Returns the cached value.
+     * Computes the value if the value has not been cached yet.
+     */
     getValue(): T;
 }
+/**
+ * A promise whose state is observable.
+ */
 export declare class ObservablePromise<T> {
     static fromFn<T>(fn: () => Promise<T>): ObservablePromise<T>;
     private readonly _value;
+    /**
+     * The promise that this object wraps.
+     */
     readonly promise: Promise<T>;
+    /**
+     * The current state of the promise.
+     * Is `undefined` if the promise didn't resolve yet.
+     */
     readonly promiseResult: IObservable<PromiseResult<T> | undefined>;
     constructor(promise: Promise<T>);
     readonly resolvedValue: import("../base.js").IObservableWithChange<T | undefined, void>;
 }
 export declare class PromiseResult<T> {
+    /**
+     * The value of the resolved promise.
+     * Undefined if the promise rejected.
+     */
     readonly data: T | undefined;
+    /**
+     * The error in case of a rejected promise.
+     * Undefined if the promise resolved.
+     */
     readonly error: unknown | undefined;
-    constructor(data: T | undefined, error: unknown | undefined);
+    constructor(
+    /**
+     * The value of the resolved promise.
+     * Undefined if the promise rejected.
+     */
+    data: T | undefined, 
+    /**
+     * The error in case of a rejected promise.
+     * Undefined if the promise resolved.
+     */
+    error: unknown | undefined);
+    /**
+     * Returns the value if the promise resolved, otherwise throws the error.
+     */
     getDataOrThrow(): T;
 }
+/**
+ * A lazy promise whose state is observable.
+ */
 export declare class ObservableLazyPromise<T> {
     private readonly _computePromise;
     private readonly _lazyValue;
+    /**
+     * Does not enforce evaluation of the promise compute function.
+     * Is undefined if the promise has not been computed yet.
+     */
     readonly cachedPromiseResult: import("../base.js").IObservableWithChange<PromiseResult<T> | undefined, void>;
     constructor(_computePromise: () => Promise<T>);
     getPromise(): Promise<T>;

package/vscode/src/vs/base/common/observableInternal/utils/utils.d.ts

@@ -5,10 +5,22 @@ export declare function observableFromPromise<T>(promise: Promise<T>): IObservab
     value?: T;
 }>;
 export declare function signalFromObservable<T>(owner: DebugOwner | undefined, observable: IObservable<T>): IObservable<void>;
+/**
+ * @deprecated Use `debouncedObservable` instead.
+ */
 export declare function debouncedObservableDeprecated<T>(observable: IObservable<T>, debounceMs: number, disposableStore: DisposableStore): IObservable<T | undefined>;
+/**
+ * Creates an observable that debounces the input observable.
+ */
 export declare function debouncedObservable<T>(observable: IObservable<T>, debounceMs: number): IObservable<T>;
 export declare function wasEventTriggeredRecently(event: Event<any>, timeoutMs: number, disposableStore: DisposableStore): IObservable<boolean>;
+/**
+ * This makes sure the observable is being observed and keeps its cache alive.
+ */
 export declare function keepObserved<T>(observable: IObservable<T>): IDisposable;
+/**
+ * This converts the given observable into an autorun.
+ */
 export declare function recomputeInitiallyAndOnChange<T>(observable: IObservable<T>, handleValue?: (value: T) => void): IDisposable;
 export declare class KeepAliveObserver implements IObserver {
     private readonly _forceRecompute;
@@ -25,4 +37,7 @@ export declare function derivedObservableWithWritableCache<T>(owner: object, com
     clearCache(transaction: ITransaction): void;
     setCache(newValue: T | undefined, tx: ITransaction | undefined): void;
 };
+/**
+ * When the items array changes, referential equal items are not mapped again.
+ */
 export declare function mapObservableArrayCached<TIn, TOut, TKey = TIn>(owner: DebugOwner, items: IObservable<readonly TIn[]>, map: (input: TIn, store: DisposableStore) => TOut, keySelector?: (input: TIn) => TKey): IObservable<readonly TOut[]>;

package/vscode/src/vs/base/common/observableInternal/utils/utilsCancellation.d.ts

@@ -1,5 +1,8 @@
 import { IReader, IObservable } from "../base.js";
 import { CancellationToken } from "../commonFacade/cancellation.js";
+/**
+ * Resolves the promise when the observables state matches the predicate.
+ */
 export declare function waitForState<T>(observable: IObservable<T | null | undefined>): Promise<T>;
 export declare function waitForState<T, TState extends T>(observable: IObservable<T>, predicate: (state: T) => state is TState, isError?: (state: T) => boolean | unknown | undefined, cancellationToken?: CancellationToken): Promise<TState>;
 export declare function waitForState<T>(observable: IObservable<T>, predicate: (state: T) => boolean, isError?: (state: T) => boolean | unknown | undefined, cancellationToken?: CancellationToken): Promise<T>;

package/vscode/src/vs/base/common/performance.d.ts

@@ -5,4 +5,7 @@ export interface PerformanceMark {
     readonly name: string;
     readonly startTime: number;
 }
+/**
+ * Returns all marks, sorted by `startTime`.
+ */
 export declare const getMarks: () => PerformanceMark[];