docs(core): add JSDocs for all exported module members

packages/core/src/index.ts

@@ -79,13 +79,25 @@ function endBatch() {
 	}
 }
 
-function batch<T>(callback: () => T): T {
+/**
+ * Combine multiple value updates into one "commit" at the end of the provided callback.
+ *
+ * Batches can be nested and changes are only flushed once the outermost batch callback
+ * completes.
+ *
+ * Accessing a signal that has been modified within a batch will reflect its updated
+ * value.
+ *
+ * @param fn The callback function.
+ * @returns The value returned by the callback.
+ */
+function batch<T>(fn: () => T): T {
 	if (batchDepth > 0) {
-		return callback();
+		return fn();
 	}
 	/*@__INLINE__**/ startBatch();
 	try {
-		return callback();
+		return fn();
 	} finally {
 		endBatch();
 	}
@@ -94,11 +106,18 @@ function batch<T>(callback: () => T): T {
 // Currently evaluated computed or effect.
 let evalContext: Computed | Effect | undefined = undefined;
 
-function untracked<T>(callback: () => T): T {
+/**
+ * Run a callback function that can access signal values without
+ * subscribing to the signal updates.
+ *
+ * @param fn The callback function.
+ * @returns The value returned by the callback.
+ */
+function untracked<T>(fn: () => T): T {
 	const prevContext = evalContext;
 	evalContext = undefined;
 	try {
-		return callback();
+		return fn();
 	} finally {
 		evalContext = prevContext;
 	}
@@ -193,6 +212,9 @@ function addDependency(signal: Signal): Node | undefined {
 	return undefined;
 }
 
+/**
+ * The base class for plain and computed signals.
+ */
 // @ts-ignore: "Cannot redeclare exported variable 'Signal'."
 //
 // A function with the same name is defined later, so we need to ignore TypeScript's
@@ -364,6 +386,12 @@ Object.defineProperty(Signal.prototype, "value", {
 	},
 });
 
+/**
+ * Create a new plain signal.
+ *
+ * @param value The initial value for the signal.
+ * @returns A new signal.
+ */
 function signal<T>(value: T): Signal<T> {
 	return new Signal(value);
 }
@@ -624,12 +652,24 @@ Object.defineProperty(Computed.prototype, "value", {
 	},
 });
 
+/**
+ * An interface for read-only signals.
+ */
 interface ReadonlySignal<T = any> extends Signal<T> {
 	readonly value: T;
 }
 
-function computed<T>(compute: () => T): ReadonlySignal<T> {
-	return new Computed(compute);
+/**
+ * Create a new signal that is computed based on the values of other signals.
+ *
+ * The returned computed signal is read-only, and its value is automatically
+ * updated when any signals accessed from within the callback function change.
+ *
+ * @param fn The effect callback.
+ * @returns A new read-only signal.
+ */
+function computed<T>(fn: () => T): ReadonlySignal<T> {
+	return new Computed(fn);
 }
 
 function cleanupEffect(effect: Effect) {
@@ -684,23 +724,22 @@ function endEffect(this: Effect, prevContext?: Computed | Effect) {
 	endBatch();
 }
 
-type EffectCleanup = () => unknown;
 declare class Effect {
-	_compute?: () => unknown | EffectCleanup;
+	_compute?: () => unknown;
 	_cleanup?: () => unknown;
 	_sources?: Node;
 	_nextBatchedEffect?: Effect;
 	_flags: number;
 
-	constructor(compute: () => unknown | EffectCleanup);
+	constructor(compute: () => unknown);
 
 	_callback(): void;
 	_start(): () => void;
 	_notify(): void;
 	_dispose(): void;
 }
 
-function Effect(this: Effect, compute: () => unknown | EffectCleanup) {
+function Effect(this: Effect, compute: () => unknown) {
 	this._compute = compute;
 	this._cleanup = undefined;
 	this._sources = undefined;
@@ -716,7 +755,7 @@ Effect.prototype._callback = function () {
 
 		const cleanup = this._compute();
 		if (typeof cleanup === "function") {
-			this._cleanup = cleanup as EffectCleanup;
+			this._cleanup = cleanup as () => unknown;
 		}
 	} finally {
 		finish();
@@ -754,8 +793,21 @@ Effect.prototype._dispose = function () {
 	}
 };
 
-function effect(compute: () => unknown | EffectCleanup): () => void {
-	const effect = new Effect(compute);
+/**
+ * Create an effect to run arbitrary code in response to signal changes.
+ *
+ * An effect tracks which signals are accessed within the given callback
+ * function `fn`, and re-runs the callback when those signals change.
+ *
+ * The callback may return a cleanup function. The cleanup function gets
+ * run once, either when the callback is next called or when the effect
+ * gets disposed, whichever happens first.
+ *
+ * @param fn The effect callback.
+ * @returns A function for disposing the effect.
+ */
+function effect(fn: () => unknown): () => void {
+	const effect = new Effect(fn);
 	try {
 		effect._callback();
 	} catch (err) {
@@ -767,4 +819,4 @@ function effect(compute: () => unknown | EffectCleanup): () => void {
 	return effect._dispose.bind(effect);
 }
 
-export { signal, computed, effect, batch, Signal, ReadonlySignal, untracked };
+export { signal, computed, effect, batch, untracked, Signal, ReadonlySignal };