chore: wrap JSDoc URLs in @see and @link tags (#17617)

* docs: wrap JSDoc URLs in @see and @link tags * fix: move curly brace to end of URL * chore: add changeset * add link text * regenerate --------- Co-authored-by: Rich Harris <rich.harris@vercel.com>
7 months ago · 863c9d6875
parent 57cb393796
commit 863c9d6875
6 changed files with 37 additions and 33 deletions
--- a/.changeset/loud-bottles-own.md
+++ b/.changeset/loud-bottles-own.md
@ -0,0 +1,5 @@
+---
+'svelte': patch
+---
+
+chore: wrap JSDoc URLs in `@see` and `@link` tags
--- a/packages/svelte/src/ambient.d.ts
+++ b/packages/svelte/src/ambient.d.ts
@ -16,7 +16,7 @@ declare module '*.svelte' {
 * let count = $state(0);
 * ```
 *
- * https://svelte.dev/docs/svelte/$state
+ * @see {@link https://svelte.dev/docs/svelte/$state Documentation}
 *
 * @param initial The initial value
 */
@ -126,7 +126,7 @@ declare namespace $state {
 	 * </button>
 	 * ```
 	 *
-	 * https://svelte.dev/docs/svelte/$state#$state.raw
+	 * @see {@link https://svelte.dev/docs/svelte/$state#$state.raw Documentation}
 	 *
 	 * @param initial The initial value
 	 */
@ -147,7 +147,7 @@ declare namespace $state {
 	 * </script>
 	 * ```
 	 *
-	 * https://svelte.dev/docs/svelte/$state#$state.snapshot
+	 * @see {@link https://svelte.dev/docs/svelte/$state#$state.snapshot Documentation}
 	 *
 	 * @param state The value to snapshot
 	 */
@ -187,7 +187,7 @@ declare namespace $state {
 * let double = $derived(count * 2);
 * ```
 *
- * https://svelte.dev/docs/svelte/$derived
+ * @see {@link https://svelte.dev/docs/svelte/$derived Documentation}
 *
 * @param expression The derived state expression
 */
@ -209,7 +209,7 @@ declare namespace $derived {
 	 * });
 	 * ```
 	 *
-	 * https://svelte.dev/docs/svelte/$derived#$derived.by
+	 * @see {@link https://svelte.dev/docs/svelte/$derived#$derived.by Documentation}
 	 */
 	export function by<T>(fn: () => T): T;

@ -251,7 +251,7 @@ declare namespace $derived {
 *
 * Does not run during server-side rendering.
 *
- * https://svelte.dev/docs/svelte/$effect
+ * @see {@link https://svelte.dev/docs/svelte/$effect Documentation}
 * @param fn The function to execute
 */
 declare function $effect(fn: () => void | (() => void)): void;
@ -270,7 +270,7 @@ declare namespace $effect {
 	 *
 	 * Does not run during server-side rendering.
 	 *
-	 * https://svelte.dev/docs/svelte/$effect#$effect.pre
+	 * @see {@link https://svelte.dev/docs/svelte/$effect#$effect.pre Documentation}
 	 * @param fn The function to execute
 	 */
 	export function pre(fn: () => void | (() => void)): void;
@ -278,7 +278,7 @@ declare namespace $effect {
 	/**
 	 * Returns the number of promises that are pending in the current boundary, not including child boundaries.
 	 *
-	 * https://svelte.dev/docs/svelte/$effect#$effect.pending
+	 * @see {@link https://svelte.dev/docs/svelte/$effect#$effect.pending Documentation}
 	 */
 	export function pending(): number;

@ -300,7 +300,7 @@ declare namespace $effect {
 	 *
 	 * This allows you to (for example) add things like subscriptions without causing memory leaks, by putting them in child effects.
 	 *
-	 * https://svelte.dev/docs/svelte/$effect#$effect.tracking
+	 * @see {@link https://svelte.dev/docs/svelte/$effect#$effect.tracking Documentation}
 	 */
 	export function tracking(): boolean;

@ -328,7 +328,7 @@ declare namespace $effect {
 	 * <button onclick={() => cleanup()}>cleanup</button>
 	 * ```
 	 *
-	 * https://svelte.dev/docs/svelte/$effect#$effect.root
+	 * @see {@link https://svelte.dev/docs/svelte/$effect#$effect.root Documentation}
 	 */
 	export function root(fn: () => void | (() => void)): () => void;

@ -364,7 +364,7 @@ declare namespace $effect {
 * let { optionalProp = 42, requiredProp, bindableProp = $bindable() }: { optionalProp?: number; requiredProps: string; bindableProp: boolean } = $props();
 * ```
 *
- * https://svelte.dev/docs/svelte/$props
+ * @see {@link https://svelte.dev/docs/svelte/$props Documentation}
 */
 declare function $props(): any;

@ -410,7 +410,7 @@ declare namespace $props {
 * let { propName = $bindable() }: { propName: boolean } = $props();
 * ```
 *
- * https://svelte.dev/docs/svelte/$bindable
+ * @see {@link https://svelte.dev/docs/svelte/$bindable Documentation}
 */
 declare function $bindable<T>(fallback?: T): T;

@ -456,7 +456,7 @@ declare namespace $bindable {
 * $inspect(x, y).with(() => { debugger; });
 * ```
 *
- * https://svelte.dev/docs/svelte/$inspect
+ * @see {@link https://svelte.dev/docs/svelte/$inspect Documentation}
 */
 declare function $inspect<T extends any[]>(
 	...values: T
@ -522,7 +522,7 @@ declare namespace $inspect {
 *
 * Only available inside custom element components, and only on the client-side.
 *
- * https://svelte.dev/docs/svelte/$host
+ * @see {@link https://svelte.dev/docs/svelte/$host Documentation}
 */
 declare function $host<El extends HTMLElement = HTMLElement>(): El;

--- a/packages/svelte/src/compiler/phases/1-parse/read/style.js
+++ b/packages/svelte/src/compiler/phases/1-parse/read/style.js
@ -568,7 +568,7 @@ function read_attribute_value(parser) {
 }

 /**
- * https://www.w3.org/TR/css-syntax-3/#ident-token-diagram
+ * @see {@link https://www.w3.org/TR/css-syntax-3/#ident-token-diagram CSS Syntax Module Level 3}
 * @param {Parser} parser
 */
 function read_identifier(parser) {
--- a/packages/svelte/src/internal/client/dom/elements/bindings/size.js
+++ b/packages/svelte/src/internal/client/dom/elements/bindings/size.js
@ -2,9 +2,8 @@ import { effect, teardown } from '../../../reactivity/effects.js';
 import { untrack } from '../../../runtime.js';

 /**
- * Resize observer singleton.
- * One listener per element only!
- * https://groups.google.com/a/chromium.org/g/blink-dev/c/z6ienONUb5A/m/F5-VcUZtBAAJ
+ * We create one listener for all elements
+ * @see {@link https://groups.google.com/a/chromium.org/g/blink-dev/c/z6ienONUb5A/m/F5-VcUZtBAAJ Explanation}
 */
 class ResizeObserverSingleton {
 	/** */
--- a/packages/svelte/tests/runtime-runes/samples/transition-component/_config.js
+++ b/packages/svelte/tests/runtime-runes/samples/transition-component/_config.js
@ -3,7 +3,7 @@ import { test } from '../../test';

 /**
 * $.component() should not break transition
- * https://github.com/sveltejs/svelte/issues/13645
+ * @see {@link https://github.com/sveltejs/svelte/issues/13645}
 */
 export default test({
 	test({ assert, raf, target }) {
--- a/packages/svelte/types/index.d.ts
+++ b/packages/svelte/types/index.d.ts
@ -3188,7 +3188,7 @@ declare module 'svelte/types/compiler/interfaces' {
 * let count = $state(0);
 * ```
 *
- * https://svelte.dev/docs/svelte/$state
+ * @see {@link https://svelte.dev/docs/svelte/$state Documentation}
 *
 * @param initial The initial value
 */
@ -3298,7 +3298,7 @@ declare namespace $state {
 	 * </button>
 	 * ```
 	 *
-	 * https://svelte.dev/docs/svelte/$state#$state.raw
+	 * @see {@link https://svelte.dev/docs/svelte/$state#$state.raw Documentation}
 	 *
 	 * @param initial The initial value
 	 */
@ -3319,7 +3319,7 @@ declare namespace $state {
 	 * </script>
 	 * ```
 	 *
-	 * https://svelte.dev/docs/svelte/$state#$state.snapshot
+	 * @see {@link https://svelte.dev/docs/svelte/$state#$state.snapshot Documentation}
 	 *
 	 * @param state The value to snapshot
 	 */
@ -3359,7 +3359,7 @@ declare namespace $state {
 * let double = $derived(count * 2);
 * ```
 *
- * https://svelte.dev/docs/svelte/$derived
+ * @see {@link https://svelte.dev/docs/svelte/$derived Documentation}
 *
 * @param expression The derived state expression
 */
@ -3381,7 +3381,7 @@ declare namespace $derived {
 	 * });
 	 * ```
 	 *
-	 * https://svelte.dev/docs/svelte/$derived#$derived.by
+	 * @see {@link https://svelte.dev/docs/svelte/$derived#$derived.by Documentation}
 	 */
 	export function by<T>(fn: () => T): T;

@ -3423,7 +3423,7 @@ declare namespace $derived {
 *
 * Does not run during server-side rendering.
 *
- * https://svelte.dev/docs/svelte/$effect
+ * @see {@link https://svelte.dev/docs/svelte/$effect Documentation}
 * @param fn The function to execute
 */
 declare function $effect(fn: () => void | (() => void)): void;
@ -3442,7 +3442,7 @@ declare namespace $effect {
 	 *
 	 * Does not run during server-side rendering.
 	 *
-	 * https://svelte.dev/docs/svelte/$effect#$effect.pre
+	 * @see {@link https://svelte.dev/docs/svelte/$effect#$effect.pre Documentation}
 	 * @param fn The function to execute
 	 */
 	export function pre(fn: () => void | (() => void)): void;
@ -3450,7 +3450,7 @@ declare namespace $effect {
 	/**
 	 * Returns the number of promises that are pending in the current boundary, not including child boundaries.
 	 *
-	 * https://svelte.dev/docs/svelte/$effect#$effect.pending
+	 * @see {@link https://svelte.dev/docs/svelte/$effect#$effect.pending Documentation}
 	 */
 	export function pending(): number;

@ -3472,7 +3472,7 @@ declare namespace $effect {
 	 *
 	 * This allows you to (for example) add things like subscriptions without causing memory leaks, by putting them in child effects.
 	 *
-	 * https://svelte.dev/docs/svelte/$effect#$effect.tracking
+	 * @see {@link https://svelte.dev/docs/svelte/$effect#$effect.tracking Documentation}
 	 */
 	export function tracking(): boolean;

@ -3500,7 +3500,7 @@ declare namespace $effect {
 	 * <button onclick={() => cleanup()}>cleanup</button>
 	 * ```
 	 *
-	 * https://svelte.dev/docs/svelte/$effect#$effect.root
+	 * @see {@link https://svelte.dev/docs/svelte/$effect#$effect.root Documentation}
 	 */
 	export function root(fn: () => void | (() => void)): () => void;

@ -3536,7 +3536,7 @@ declare namespace $effect {
 * let { optionalProp = 42, requiredProp, bindableProp = $bindable() }: { optionalProp?: number; requiredProps: string; bindableProp: boolean } = $props();
 * ```
 *
- * https://svelte.dev/docs/svelte/$props
+ * @see {@link https://svelte.dev/docs/svelte/$props Documentation}
 */
 declare function $props(): any;

@ -3582,7 +3582,7 @@ declare namespace $props {
 * let { propName = $bindable() }: { propName: boolean } = $props();
 * ```
 *
- * https://svelte.dev/docs/svelte/$bindable
+ * @see {@link https://svelte.dev/docs/svelte/$bindable Documentation}
 */
 declare function $bindable<T>(fallback?: T): T;

@ -3628,7 +3628,7 @@ declare namespace $bindable {
 * $inspect(x, y).with(() => { debugger; });
 * ```
 *
- * https://svelte.dev/docs/svelte/$inspect
+ * @see {@link https://svelte.dev/docs/svelte/$inspect Documentation}
 */
 declare function $inspect<T extends any[]>(
 	...values: T
@ -3694,7 +3694,7 @@ declare namespace $inspect {
 *
 * Only available inside custom element components, and only on the client-side.
 *
- * https://svelte.dev/docs/svelte/$host
+ * @see {@link https://svelte.dev/docs/svelte/$host Documentation}
 */
 declare function $host<El extends HTMLElement = HTMLElement>(): El;