From ff219225b5eb7c34dc4fd03e43b101a57650c20c Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Sun, 4 Oct 2026 12:10:27 +0900
Subject: [PATCH 1/2] docs(svelte-query): add JSDoc to the exported classes,
 methods, and arrow functions

---
 packages/svelte-query/src/containers.svelte.ts | 8 ++++++++
 packages/svelte-query/src/utils.svelte.ts      | 8 ++++++++
 2 files changed, 16 insertions(+)

diff --git a/packages/svelte-query/src/containers.svelte.ts b/packages/svelte-query/src/containers.svelte.ts
index 046e32fe5ac..dae0940ef73 100644
--- a/packages/svelte-query/src/containers.svelte.ts
+++ b/packages/svelte-query/src/containers.svelte.ts
@@ -8,6 +8,10 @@ type Subscriber = (update: VoidFn) => void | VoidFn
  */
 export type Box<T> = { current: T }
 
+/**
+ * A {@link Box} whose `current` value is computed on each read, and that notifies the reactive
+ * contexts reading it through the given subscriber.
+ */
 export class ReactiveValue<T> implements Box<T> {
   #fn
   #subscribe
@@ -17,6 +21,10 @@ export class ReactiveValue<T> implements Box<T> {
     this.#subscribe = createSubscriber((update) => onSubscribe(update))
   }
 
+  /**
+   * Subscribes the reactive context reading it, then computes the value.
+   * @returns The value returned by the compute function.
+   */
   get current() {
     this.#subscribe()
     return this.#fn()
diff --git a/packages/svelte-query/src/utils.svelte.ts b/packages/svelte-query/src/utils.svelte.ts
index 9cd9ed9e529..bedcb5607be 100644
--- a/packages/svelte-query/src/utils.svelte.ts
+++ b/packages/svelte-query/src/utils.svelte.ts
@@ -19,6 +19,14 @@ function runEffect(
   }
 }
 type Getter<T> = () => T
+/**
+ * Runs `effect` whenever the values returned by `sources` change, skipping the first run. The
+ * effect receives the new and previous values, and is called untracked, so only `sources` are
+ * tracked.
+ * @param sources - The getter, or array of getters, to watch.
+ * @param flush - Whether to run after (`'post'`) or before (`'pre'`) the DOM updates.
+ * @param effect - Called with the new and previous values. It may return a cleanup function.
+ */
 export const watchChanges = <T>(
   sources: Getter<T> | Array<Getter<T>>,
   flush: 'post' | 'pre',

From c9e27b8a7237b19c9c8ef168b7dd9d32a4399f2f Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Sun, 4 Oct 2026 12:35:39 +0900
Subject: [PATCH 2/2] docs(svelte-query/utils): describe that 'watchChanges'
 runs on every change of the state its sources read

---
 packages/svelte-query/src/utils.svelte.ts | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/packages/svelte-query/src/utils.svelte.ts b/packages/svelte-query/src/utils.svelte.ts
index bedcb5607be..83054d6f44b 100644
--- a/packages/svelte-query/src/utils.svelte.ts
+++ b/packages/svelte-query/src/utils.svelte.ts
@@ -20,9 +20,9 @@ function runEffect(
 }
 type Getter<T> = () => T
 /**
- * Runs `effect` whenever the values returned by `sources` change, skipping the first run. The
- * effect receives the new and previous values, and is called untracked, so only `sources` are
- * tracked.
+ * Runs `effect` whenever the reactive state read by `sources` changes, even if they return the
+ * same values, skipping the first run. The effect receives the new and previous values, and is
+ * called untracked, so only `sources` are tracked.
  * @param sources - The getter, or array of getters, to watch.
  * @param flush - Whether to run after (`'post'`) or before (`'pre'`) the DOM updates.
  * @param effect - Called with the new and previous values. It may return a cleanup function.