docs: AI-readiness JSDoc handoff prep

Backfill JSDoc examples on previously-undocumented public APIs flagged in
the v2 docs categorization audit (`getObserver`, `isDisposed`,
`createRenderEffect`, `onCleanup`, `createErrorBoundary`,
`createLoadingBoundary`, `createRevealOrder`, `flatten`,
`enableExternalSource`, `NotReadyError`, `NoHydration`, `Hydration`,
`isServer`, `isDev`).

Normalize inline JSDoc code fences to `@example` tags on the JSX components
(`<For>`, `<Repeat>`, `<Switch>`, `<Errored>`, `<Reveal>`, `dynamic`,
`<Dynamic>`) so the doc generator can extract examples uniformly.

Tag cross-package wiring and compiler-emitted exports with `@internal` so
the doc generator can hide them from the user-facing surface (`getContext`,
`setContext`, `createOwner`, `getNextChildId` / `peekNextChildId`,
`enforceLoadingBoundary`, the store / refresh brand symbols, `\$DEVCOMP`,
`sharedConfig`, `enableHydration`, `NoHydrateContext`, the `ssr*` helpers
in `server-mock`, `escape`, `resolveSSRNode`, `mergeProps`, `ssrHandleError`
/ `ssrRunInScope`).

Mention `isEqual` as the default on the `equals` field of `SignalOptions`
and `MemoOptions` so the equals comparator has a docs landing spot.

Made-with: Cursor

Author: ryansolid

.changeset/ai-readiness-docs-handoff.md

@@ -0,0 +1,7 @@
+---
+"solid-js": patch
+"@solidjs/web": patch
+"@solidjs/signals": patch
+---
+
+Docs prep for the 2.0 reference auto-generation pass: backfill JSDoc examples on previously-undocumented public APIs (`getObserver`, `isDisposed`, `createRenderEffect`, `onCleanup`, `createErrorBoundary`, `createLoadingBoundary`, `createRevealOrder`, `flatten`, `enableExternalSource`, `NotReadyError`, `NoHydration`, `Hydration`, `isServer`, `isDev`); normalize inline JSDoc code fences to `@example` tags on the JSX components (`<For>`, `<Repeat>`, `<Switch>`, `<Errored>`, `<Reveal>`, `dynamic`, `<Dynamic>`); and tag cross-package wiring / compiler-emitted exports with `@internal` so the doc generator can hide them from the user-facing surface (`getContext`, `setContext`, `createOwner`, `getNextChildId`, `peekNextChildId`, `enforceLoadingBoundary`, `sharedConfig`, `enableHydration`, `NoHydrateContext`, `$DEVCOMP`, `$PROXY`, `$REFRESH`, `$TRACK`, `$TARGET`, `$DELETED`, `ssr*` helpers, `escape`, `resolveSSRNode`, `mergeProps`, `ssrHandleError`, `ssrRunInScope`). Also extends the `equals` field JSDoc on `SignalOptions` / `MemoOptions` to mention `isEqual` as the default.

packages/solid-signals/src/boundaries.ts

@@ -407,6 +407,17 @@ function createCollectionBoundary<T>(
  * @param fallback the fallback shown while async reads in `fn` are unresolved
  * @param options `on` — accessor whose value scopes the boundary; when set,
  *   transitions caused by writes to other reactive sources are *not* caught
+ *
+ * @example
+ * ```tsx
+ * // Custom boundary component built on top of the primitive.
+ * function MyLoading(props: { fallback: JSX.Element; children: JSX.Element }) {
+ *   return createLoadingBoundary(
+ *     () => props.children,
+ *     () => props.fallback
+ *   ) as unknown as JSX.Element;
+ * }
+ * ```
  */
 export function createLoadingBoundary(
   fn: () => any,
@@ -424,6 +435,20 @@ export function createLoadingBoundary(
  *
  * App code should use `<Errored fallback={...}>` instead — reach for this only
  * when authoring custom boundary components.
+ *
+ * @example
+ * ```tsx
+ * // Custom boundary that wraps the primitive and adds telemetry.
+ * function TracedErrored(props: { fallback: (e: unknown) => JSX.Element; children: JSX.Element }) {
+ *   return createErrorBoundary(
+ *     () => props.children,
+ *     (err, reset) => {
+ *       reportError(err);
+ *       return props.fallback(err);
+ *     }
+ *   ) as unknown as JSX.Element;
+ * }
+ * ```
  */
 export function createErrorBoundary<U>(
   fn: () => any,
@@ -469,6 +494,17 @@ export function createErrorBoundary<U>(
  * - `together` — every direct slot is minimally ready.
  * - `natural` — any direct slot has visible content (leaves on resolve; nested
  *   composites when fully ready, since natural treats composites as atomic).
+ *
+ * @example
+ * ```ts
+ * // Primitive form of `<Reveal>` — coordinate sibling loading boundaries
+ * // programmatically. App code uses the JSX `<Reveal>` component instead.
+ * // Both options are accessors so they can react to state changes.
+ * createRevealOrder(
+ *   () => renderSiblings(),
+ *   { order: () => mode(), collapsed: () => true }
+ * );
+ * ```
  */
 export function createRevealOrder<T>(
   fn: () => T,
@@ -510,6 +546,15 @@ export function createRevealOrder<T>(
  * @param options
  *   - `skipNonRendered` — drop values that won't render
  *   - `doNotUnwrap` — leave function children as-is (caller will resolve)
+ *
+ * @example
+ * ```ts
+ * // Custom renderer walking a children tree manually. Most authors should
+ * // use `children()` from solid-js, which memoizes the resolved value.
+ * function renderChildren(value: unknown): unknown {
+ *   return flatten(value, { skipNonRendered: true });
+ * }
+ * ```
  */
 export function flatten(
   children: any,

packages/solid-signals/src/core/constants.ts

@@ -36,6 +36,13 @@ export const SUPPORTS_PROXY = typeof Proxy === "function";
 
 export const defaultContext = {};
 
+/**
+ * Brand symbol used by `Refreshable<T>` values (projection stores, async
+ * memos) to expose their underlying computation to `refresh()`. Not part of
+ * the user-facing API.
+ *
+ * @internal
+ */
 export const $REFRESH = Symbol("refresh");
 
 /**

packages/solid-signals/src/core/context.ts

@@ -22,10 +22,14 @@ export function createContext<T>(defaultValue?: T, description?: string): Contex
 }
 
 /**
- * Attempts to get a context value for the given key.
+ * Low-level owner-targeted context read. The user-facing read API is
+ * `useContext` (in `solid-js`), which wraps this primitive. Exposed here for
+ * cross-package wiring (e.g. hydration-aware context plumbing).
  *
  * @throws `NoOwnerError` if there's no owner at the time of call.
  * @throws `ContextNotFoundError` if a context value has not been set yet.
+ *
+ * @internal
  */
 export function getContext<T>(context: Context<T>, owner: Owner | null = getOwner()): T {
   if (!owner) {
@@ -44,9 +48,13 @@ export function getContext<T>(context: Context<T>, owner: Owner | null = getOwne
 }
 
 /**
- * Attempts to set a context value on the parent scope with the given key.
+ * Low-level owner-targeted context write. The user-facing API is
+ * `createContext` (in `solid-js`); its provider component wraps this
+ * primitive. Exposed here for cross-package wiring.
  *
  * @throws `NoOwnerError` if there's no owner at the time of call.
+ *
+ * @internal
  */
 export function setContext<T>(context: Context<T>, value?: T, owner: Owner | null = getOwner()) {
   if (!owner) {

packages/solid-signals/src/core/error.ts

@@ -1,3 +1,27 @@
+/**
+ * Thrown by a tracked read whose value is currently pending (an async memo /
+ * `createSignal(asyncFn)` / projection / store derivation that hasn't settled
+ * yet). Surfacing through the reactive graph is what suspends the consumer
+ * scope — the nearest enclosing `<Loading>` boundary catches the throw and
+ * renders its fallback until the source resolves.
+ *
+ * App code rarely catches this directly; `<Loading>` is the canonical
+ * handler. The error type is exposed for advanced cases — e.g. interop layers
+ * that bridge Solid's pending-throw protocol to a different async strategy,
+ * or tests that want to assert on the suspension shape.
+ *
+ * @example
+ * ```ts
+ * // Advanced: distinguish "not ready yet" from a real error in custom
+ * // boundary plumbing. App code should rely on `<Loading>` / `<Errored>`.
+ * try {
+ *   const value = readReactiveSource();
+ * } catch (err) {
+ *   if (err instanceof NotReadyError) throw err; // re-throw to suspend
+ *   reportError(err);
+ * }
+ * ```
+ */
 export class NotReadyError extends Error {
   constructor(public source: any) {
     super();

packages/solid-signals/src/core/external.ts

@@ -25,6 +25,25 @@ export let externalSourceConfig: {
  * @param config.factory receives `(fn, trigger)` — wrap fn execution in external tracking,
  *   call trigger when external deps change. Return `{ track, dispose }`.
  * @param config.untrack optional wrapper for `untrack` — disables external tracking too.
+ *
+ * @example
+ * ```ts
+ * // Bridge an external "subscribe / notify" library into Solid's graph.
+ * // `factory` wraps every Solid compute so the external library can attach
+ * // its own dependency tracker; `trigger` re-runs the compute on external
+ * // change. `untrack` mirrors Solid's `untrack()` into the external library
+ * // so that reads inside `untrack(...)` don't get tracked twice.
+ * enableExternalSource({
+ *   factory: (compute, trigger) => {
+ *     const sub = externalLib.subscribe(trigger);
+ *     return {
+ *       track: prev => externalLib.run(() => compute(prev)),
+ *       dispose: () => sub.unsubscribe()
+ *     };
+ *   },
+ *   untrack: fn => externalLib.untracked(fn)
+ * });
+ * ```
  */
 export function enableExternalSource(config: ExternalSourceConfig): void {
   const { factory, untrack: untrackFn = fn => fn() } = config;

packages/solid-signals/src/core/owner.ts

@@ -98,10 +98,22 @@ function childId(owner: Owner, consume: boolean): string {
   throw new Error("Cannot get child id from owner without an id");
 }
 
+/**
+ * Allocates and returns the next stable child id for `owner`. Used by
+ * hydration plumbing and `createUniqueId`. Not part of the user-facing API.
+ *
+ * @internal
+ */
 export function getNextChildId(owner: Owner): string {
   return childId(owner, true);
 }
 
+/**
+ * Returns the *next* child id for `owner` without consuming it. Used by
+ * hydration plumbing to peek at the id a future child will receive.
+ *
+ * @internal
+ */
 export function peekNextChildId(owner: Owner): string {
   return childId(owner, false);
 }
@@ -118,6 +130,15 @@ function formatId(prefix: string, id: number) {
  * Used by reactive primitives that need to know whether they're inside a
  * tracking scope. App code rarely needs this — see `getOwner()` for the
  * lifecycle owner instead.
+ *
+ * @example
+ * ```ts
+ * // Library predicate: only register a hot-path subscription when the
+ * // caller is inside a tracking scope (memo / effect compute / JSX).
+ * function trackIfTracked(source: () => unknown) {
+ *   if (getObserver()) source();
+ * }
+ * ```
  */
 export function getObserver(): Owner | null {
   if (pendingCheckActive || latestReadActive) return PENDING_OWNER;
@@ -158,15 +179,33 @@ export function cleanup(fn: Disposable): Disposable {
   return fn;
 }
 
-/** Returns `true` if the owner has been disposed (or marked zombie pending disposal). */
+/**
+ * Returns `true` if the owner has been disposed (or marked zombie pending
+ * disposal). Pair with a captured owner to bail out of late callbacks whose
+ * surrounding component already unmounted.
+ *
+ * @example
+ * ```ts
+ * function onSettleSafe(fn: () => void) {
+ *   const owner = getOwner();
+ *   queueMicrotask(() => {
+ *     if (owner && isDisposed(owner)) return; // component unmounted; skip
+ *     runWithOwner(owner, fn);
+ *   });
+ * }
+ * ```
+ */
 export function isDisposed(node: Owner): boolean {
   return !!((node as any)._flags & (REACTIVE_DISPOSED | REACTIVE_ZOMBIE));
 }
 
 /**
  * Creates a fresh owner attached as a child of the current owner (or as a
- * detached root if there is none). Mostly used by framework internals to
- * group cleanups; app code should prefer `createRoot()` or `runWithOwner()`.
+ * detached root if there is none). Used by framework internals to group
+ * cleanups; app code should use `createRoot()` (host a reactive scope outside
+ * a component) or `runWithOwner()` (re-enter a captured owner).
+ *
+ * @internal
  */
 export function createOwner(options?: { id?: string; transparent?: boolean }) {
   const parent = context;

packages/solid-signals/src/core/scheduler.ts

@@ -80,6 +80,14 @@ function sweepTransientStoreNodes(): void {
 export function resetUnhandledAsync(): void {
   _hitUnhandledAsync = false;
 }
+/**
+ * Toggles the dev-mode "must be inside a `<Loading>` boundary" enforcement
+ * window. Only `render()` calls this — wrapping the initial mount so that a
+ * top-level uncaught async read surfaces the diagnostic. Not part of the
+ * user-facing API.
+ *
+ * @internal
+ */
 export function enforceLoadingBoundary(enabled: boolean): void {
   _enforceLoadingBoundary = enabled;
 }

packages/solid-signals/src/signals.ts

@@ -49,6 +49,18 @@ import { globalQueue } from "./core/scheduler.js";
  *
  * Cannot be used inside `createTrackedEffect` or `onSettled` — return a
  * cleanup function from the callback body instead.
+ *
+ * @example
+ * ```ts
+ * // Library shape: thread a resource's disposal into a *captured* owner
+ * // from a factory that has no settle-phase setup of its own. `onSettled`
+ * // would queue a callback we don't need; `onCleanup` is the leaner
+ * // primitive when the only job is "register disposal on this owner".
+ * function bindToOwner<T extends { dispose(): void }>(owner: Owner, resource: T): T {
+ *   runWithOwner(owner, () => onCleanup(() => resource.dispose()));
+ *   return resource;
+ * }
+ * ```
  */
 export function onCleanup(fn: Disposable): Disposable {
   if (__DEV__) {
@@ -151,7 +163,12 @@ export interface EffectOptions extends BaseEffectOptions {
 export interface SignalOptions<T> {
   /** Debug name (dev mode only) */
   name?: string;
-  /** Custom equality function, or `false` to always notify subscribers */
+  /**
+   * Custom equality function, or `false` to always notify subscribers.
+   * Defaults to reference equality (`isEqual`). Pass a comparator (e.g.
+   * `(a, b) => a.id === b.id`) for value-based equality, or `false` to
+   * notify on every write regardless of equality.
+   */
   equals?: false | ((prev: T, next: T) => boolean);
   /** Suppress dev-mode warnings when writing inside an owned scope */
   ownedWrite?: boolean;
@@ -171,7 +188,12 @@ export interface MemoOptions<T> {
   name?: string;
   /** When true, the owner is invisible to the ID scheme -- inherits parent ID and doesn't consume a childCount slot */
   transparent?: boolean;
-  /** Custom equality function, or `false` to always notify subscribers */
+  /**
+   * Custom equality function, or `false` to always notify subscribers.
+   * Defaults to reference equality (`isEqual`). Pass a comparator (e.g.
+   * `(a, b) => a.id === b.id`) for value-based equality, or `false` to
+   * notify on every recompute regardless of equality.
+   */
   equals?: false | ((prev: T, next: T) => boolean);
   /** Callback invoked when the computed loses all subscribers */
   unobserved?: () => void;
@@ -385,13 +407,29 @@ export function createEffect<T>(
  * Creates a reactive computation that runs during the render phase as DOM elements
  * are created and updated but not necessarily connected.
  *
+ * Same compute / effect split as `createEffect`, but scheduled inside the render
+ * queue rather than after it. Reach for this only when authoring renderer
+ * plumbing (custom DOM bindings, JSX-generated `insert()` / `spread()` calls).
+ * App code should use `createEffect`.
+ *
  * ```typescript
  * createRenderEffect<T>(compute, effectFn, options?: EffectOptions);
  * ```
  * @param compute a function that receives its previous value and returns a new value used to react on a computation
  * @param effectFn a function that receives the new value and is used to perform side effects
  * @param options `EffectOptions` -- name, defer, schedule
  *
+ * @example
+ * ```ts
+ * // Custom directive: bind an element's textContent to a reactive source.
+ * function bindText(el: HTMLElement, source: () => string) {
+ *   createRenderEffect(
+ *     () => source(),
+ *     value => { el.textContent = value; }
+ *   );
+ * }
+ * ```
+ *
  * @description https://docs.solidjs.com/reference/secondary-primitives/create-render-effect
  */
 export function createRenderEffect<T>(

packages/solid-signals/src/store/store.ts

@@ -58,6 +58,12 @@ export type NoFn<T> = T extends Function ? never : T;
 type DataNode = Signal<any>;
 type DataNodes = Record<PropertyKey, DataNode>;
 
+/**
+ * Brand symbols used internally by the store proxy / projection plumbing.
+ * Cross-package wiring; not part of the user-facing API.
+ *
+ * @internal
+ */
 export const $TRACK = Symbol(__DEV__ ? "STORE_TRACK" : 0),
   $TARGET = Symbol(__DEV__ ? "STORE_TARGET" : 0),
   $PROXY = Symbol(__DEV__ ? "STORE_PROXY" : 0),