improve accuracy of docs

Author: LadyBluenotes

src/routes/reference/components/no-hydration.mdx

@@ -39,14 +39,14 @@ Content inside the boundary.
 
 - **Type:** `JSX.Element`
 
-Returns the server-rendered children.
+Returns the children during server and client-only rendering.
 
 ## Behavior
 
 - During server rendering, children inside `<NoHydration>` render normally.
 - During client hydration, Solid leaves the existing server-rendered DOM in place and does not hydrate that subtree.
+- In client-only rendering, `<NoHydration>` renders its children normally.
 - Interactive behavior inside the boundary does not hydrate on the client.
-- Placing `<Hydration>` inside `<NoHydration>` does not override the no-hydration behavior.
 
 ## Examples
 
@@ -56,9 +56,11 @@ Returns the server-rendered children.
 function Example() {
 	return (
 		<div>
-			<button>Interactive button</button>
+			<button onClick={() => console.log("hydrated")}>Hydrated button</button>
 			<NoHydration>
-				<div innerHTML={"<strong>Server-rendered only</strong>"} />
+				<div>
+					<strong>Rendered on the server without hydration</strong>
+				</div>
 			</NoHydration>
 		</div>
 	);

src/routes/reference/components/suspense-list.mdx

@@ -56,7 +56,7 @@ Order used to reveal child boundaries.
 
 - **Type:** `"collapsed" | "hidden"`
 
-Controls fallback visibility for later items after the first still-pending item.
+Controls fallback visibility for later items after the first still-pending item in ordered reveal modes.
 
 ## Return value
 
@@ -71,23 +71,36 @@ Returns the coordinated suspense boundaries.
 - `revealOrder="together"` reveals all items only after all coordinated boundaries are ready.
 - With `tail="collapsed"`, the first still-pending item can keep its fallback visible, while later pending items hide theirs.
 - With `tail="hidden"`, pending items after the first still-pending item hide their fallbacks.
+- `<SuspenseList>` coordinates child suspense boundaries. It does not suspend by itself.
 
 ## Examples
 
 ### Basic usage
 
 ```tsx
-const resource = {
-	user: { name: "Ada" },
-	posts: ["First post"],
+import { createResource, Suspense } from "solid-js";
+
+const delayed = async <T,>(value: T, ms: number) => {
+	await new Promise((resolve) => setTimeout(resolve, ms));
+	return value;
 };
 
+function ProfileDetails() {
+	const [user] = createResource(() => delayed({ name: "Ada" }, 500));
+	return <h2>{user()?.name}</h2>;
+}
+
+function ProfileTimeline() {
+	const [posts] = createResource(() => delayed(["First post"], 1000));
+	return <ul>{posts()?.map((post) => <li>{post}</li>)}</ul>;
+}
+
 <SuspenseList revealOrder="forwards" tail="collapsed">
 	<Suspense fallback={<h2>Loading profile...</h2>}>
-		<ProfileDetails user={resource.user} />
+		<ProfileDetails />
 	</Suspense>
 	<Suspense fallback={<h2>Loading posts...</h2>}>
-		<ProfileTimeline posts={resource.posts} />
+		<ProfileTimeline />
 	</Suspense>
 </SuspenseList>;
 ```

src/routes/reference/components/suspense.mdx

@@ -12,10 +12,10 @@ tags:
   - components
 version: "1.0"
 description: >-
-  Render fallback content while resources read under the boundary are pending.
+  Render fallback content while suspense-tracked async dependencies under the boundary are pending.
 ---
 
-`<Suspense>` renders `fallback` while resources read under its boundary are pending.
+`<Suspense>` renders `fallback` while suspense-tracked async dependencies under its boundary are pending.
 
 ## Import
 
@@ -38,7 +38,7 @@ function Suspense(props: {
 
 - **Type:** `JSX.Element`
 
-Content rendered while tracked resources are pending.
+Content rendered while suspense-tracked async dependencies are pending.
 
 ### `children`
 
@@ -50,34 +50,68 @@ Subtree inside the suspense boundary.
 
 - **Type:** `JSX.Element`
 
-Returns the rendered subtree or `fallback` content depending on pending tracked resources.
+Returns the rendered subtree or `fallback` content depending on pending suspense-tracked async dependencies.
 
 ## Behavior
 
-- When a resource is read inside the boundary, `<Suspense>` renders `fallback` until the pending tracked resources resolve.
-- `<Suspense>` is non-blocking: the subtree can continue running before the boundary reveals the resolved content in the DOM.
-- Nested suspense boundaries handle resources read under the nearest boundary.
+- When a suspense-tracked async dependency is read inside the boundary, `<Suspense>` renders `fallback` until the pending work resolves.
+- `<Suspense>` is non-blocking: the subtree can continue running and create reactive owners before the boundary reveals the resolved content in the DOM.
+- Nested suspense boundaries handle suspense-tracked async dependencies under the nearest boundary.
 - `onMount` and `createEffect` inside the suspended subtree run after the boundary resolves.
 
 ## Examples
 
 ### Basic usage
 
 ```tsx
-<Suspense fallback={<LoadingSpinner />}>
-	<AsyncComponent />
-</Suspense>
+import { createResource } from "solid-js";
+
+const fetchMessage = async () => {
+	await new Promise((resolve) => setTimeout(resolve, 1000));
+	return "Loaded";
+};
+
+function AsyncMessage() {
+	const [message] = createResource(fetchMessage);
+	return <p>{message()}</p>;
+}
+
+<Suspense fallback={<p>Loading...</p>}>
+	<AsyncMessage />
+</Suspense>;
 ```
 
 ### Nested suspense
 
 ```tsx
+import { createResource } from "solid-js";
+
+const fetchTitle = async () => {
+	await new Promise((resolve) => setTimeout(resolve, 500));
+	return "Profile";
+};
+
+const fetchDetails = async () => {
+	await new Promise((resolve) => setTimeout(resolve, 1000));
+	return "Details loaded";
+};
+
+function Title() {
+	const [title] = createResource(fetchTitle);
+	return <h1>{title()}</h1>;
+}
+
+function Details() {
+	const [details] = createResource(fetchDetails);
+	return <p>{details()}</p>;
+}
+
 <Suspense fallback={<div>Loading page...</div>}>
-	<h1>{title()}</h1>
-	<Suspense fallback={<div>Loading details</div>}>
-		<DataComponent>{data()}</DataComponent>
+	<Title />
+	<Suspense fallback={<div>Loading details...</div>}>
+		<Details />
 	</Suspense>
-</Suspense>
+</Suspense>;
 ```
 
 ## Related

src/routes/reference/components/switch-and-match.mdx

@@ -91,26 +91,41 @@ Returns the selected branch or the `fallback` content.
 
 - `<Switch>` evaluates its child `<Match>` elements in order and renders only the first truthy branch.
 - If no branch matches, `<Switch>` renders `fallback`.
-- With `keyed={false}`, function children in `<Match>` receive an accessor that can only be read while that branch remains selected. With `keyed={true}`, they receive the value directly.
+- Function children in `<Match>` are wrapped in [`untrack`](/reference/reactive-utilities/untrack).
+- With `keyed={false}`, function children in `<Match>` receive an accessor that can only be read while that branch remains selected. Replacing one truthy value with another truthy value does not recreate the child block.
+- With `keyed={true}`, function children receive the current value directly, and changing the `when` value recreates the child block even when it remains truthy.
 
 ## Examples
 
 ### Basic usage
 
 ```tsx
-<Switch fallback={<p>Unknown status</p>}>
-	<Match when={state.status === "loading"}>
-		<p>Loading...</p>
-	</Match>
-	<Match when={state.status === "success"}>
-		<p>Saved</p>
-	</Match>
-	<Match when={state.status === "error"}>
-		<p>Failed</p>
-	</Match>
-</Switch>
+import { createSignal } from "solid-js";
+
+const [status, setStatus] = createSignal<"loading" | "success" | "error">(
+	"loading"
+);
+
+<>
+	<button onClick={() => setStatus("loading")}>Loading</button>
+	<button onClick={() => setStatus("success")}>Success</button>
+	<button onClick={() => setStatus("error")}>Error</button>
+
+	<Switch fallback={<p>Unknown status</p>}>
+		<Match when={status() === "loading"}>
+			<p>Loading...</p>
+		</Match>
+		<Match when={status() === "success"}>
+			<p>Saved</p>
+		</Match>
+		<Match when={status() === "error"}>
+			<p>Failed</p>
+		</Match>
+	</Switch>
+</>;
 ```
 
 ## Related
 
 - [`<Show>`](/reference/components/show)
+- [`untrack`](/reference/reactive-utilities/untrack)