From 09da0215729eb24ec67cd6427b2ec7855d4a6cda Mon Sep 17 00:00:00 2001
From: Rich Harris <rich.harris@vercel.com>
Date: Mon, 19 May 2025 17:33:34 -0400
Subject: [PATCH] god i hate overloads

---
 packages/svelte/src/attachments/index.js | 38 ++++++++++++++++++++++--
 packages/svelte/types/index.d.ts         | 32 ++++++++++++++++++--
 2 files changed, 66 insertions(+), 4 deletions(-)

diff --git a/packages/svelte/src/attachments/index.js b/packages/svelte/src/attachments/index.js
index 0ff1f60fb1..f5e26571c7 100644
--- a/packages/svelte/src/attachments/index.js
+++ b/packages/svelte/src/attachments/index.js
@@ -32,6 +32,19 @@ export function createAttachmentKey() {
 }
 
 /**
+ * Converts an [action](https://svelte.dev/docs/svelte/use) into an [attachment](https://svelte.dev/docs/svelte/@attach) keeping the same behavior.
+ * It's useful if you want to start using attachments on components but you have actions provided by a library.
+ *
+ * Note that the second argument, if provided, must be a function that _returns_ the argument to the
+ * action function, not the argument itself.
+ *
+ * ```svelte
+ * <!-- with an action -->
+ * <div use:foo={bar}>...</div>
+ *
+ * <!-- with an attachment -->
+ * <div {@attach fromAction(foo, () => bar)}>...</div>
+ * ```
  * @template {EventTarget} E
  * @template {unknown} T
  * @overload
@@ -40,18 +53,39 @@ export function createAttachmentKey() {
  * @returns {Attachment<E>}
  */
 /**
+ * Converts an [action](https://svelte.dev/docs/svelte/use) into an [attachment](https://svelte.dev/docs/svelte/@attach) keeping the same behavior.
+ * It's useful if you want to start using attachments on components but you have actions provided by a library.
+ *
+ * Note that the second argument, if provided, must be a function that _returns_ the argument to the
+ * action function, not the argument itself.
+ *
+ * ```svelte
+ * <!-- with an action -->
+ * <div use:foo={bar}>...</div>
+ *
+ * <!-- with an attachment -->
+ * <div {@attach fromAction(foo, () => bar)}>...</div>
+ * ```
  * @template {EventTarget} E
  * @overload
  * @param {Action<E, void> | ((element: E) => void | ActionReturn<void>)} action The action function
  * @returns {Attachment<E>}
  */
 /**
- * Converts an Action into an Attachment keeping the same behavior. It's useful if you want to start using
- * attachments on Components but you have library provided actions.
+ * Converts an [action](https://svelte.dev/docs/svelte/use) into an [attachment](https://svelte.dev/docs/svelte/@attach) keeping the same behavior.
+ * It's useful if you want to start using attachments on components but you have actions provided by a library.
  *
  * Note that the second argument, if provided, must be a function that _returns_ the argument to the
  * action function, not the argument itself.
  *
+ * ```svelte
+ * <!-- with an action -->
+ * <div use:foo={bar}>...</div>
+ *
+ * <!-- with an attachment -->
+ * <div {@attach fromAction(foo, () => bar)}>...</div>
+ * ```
+ *
  * @template {EventTarget} E
  * @template {unknown} T
  * @param {Action<E, T> | ((element: E, arg: T) => void | ActionReturn<T>)} action The action function
diff --git a/packages/svelte/types/index.d.ts b/packages/svelte/types/index.d.ts
index 59c8d7ff15..c03da56856 100644
--- a/packages/svelte/types/index.d.ts
+++ b/packages/svelte/types/index.d.ts
@@ -659,9 +659,37 @@ declare module 'svelte/attachments' {
 	 * @since 5.29
 	 */
 	export function createAttachmentKey(): symbol;
-
+	/**
+	 * Converts an [action](https://svelte.dev/docs/svelte/use) into an [attachment](https://svelte.dev/docs/svelte/@attach) keeping the same behavior.
+	 * It's useful if you want to start using attachments on components but you have actions provided by a library.
+	 *
+	 * Note that the second argument, if provided, must be a function that _returns_ the argument to the
+	 * action function, not the argument itself.
+	 *
+	 * ```svelte
+	 * <!-- with an action -->
+	 * <div use:foo={bar}>...</div>
+	 *
+	 * <!-- with an attachment -->
+	 * <div {@attach fromAction(foo, () => bar)}>...</div>
+	 * ```
+	 * */
 	export function fromAction<E extends EventTarget, T extends unknown>(action: Action<E, T> | ((element: E, arg: T) => void | ActionReturn<T>), fn: () => T): Attachment<E>;
-
+	/**
+	 * Converts an [action](https://svelte.dev/docs/svelte/use) into an [attachment](https://svelte.dev/docs/svelte/@attach) keeping the same behavior.
+	 * It's useful if you want to start using attachments on components but you have actions provided by a library.
+	 *
+	 * Note that the second argument, if provided, must be a function that _returns_ the argument to the
+	 * action function, not the argument itself.
+	 *
+	 * ```svelte
+	 * <!-- with an action -->
+	 * <div use:foo={bar}>...</div>
+	 *
+	 * <!-- with an attachment -->
+	 * <div {@attach fromAction(foo, () => bar)}>...</div>
+	 * ```
+	 * */
 	export function fromAction<E extends EventTarget>(action: Action<E, void> | ((element: E) => void | ActionReturn<void>)): Attachment<E>;
 
 	export {};