docs: expand docs for fail method (#13789)

Author: benmccann

packages/kit/src/exports/index.js

@@ -180,14 +180,14 @@ export function text(body, init) {
 }
 
 /**
- * Create an `ActionFailure` object.
+ * Create an `ActionFailure` object. Call when form submission fails.
  * @param {number} status The [HTTP status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#client_error_responses). Must be in the range 400-599.
  * @overload
  * @param {number} status
  * @returns {import('./public.js').ActionFailure<undefined>}
  */
 /**
- * Create an `ActionFailure` object.
+ * Create an `ActionFailure` object. Call when form submission fails.
  * @template {Record<string, unknown> | undefined} [T=undefined]
  * @param {number} status The [HTTP status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#client_error_responses). Must be in the range 400-599.
  * @param {T} data Data associated with the failure (e.g. validation errors)
@@ -197,7 +197,7 @@ export function text(body, init) {
  * @returns {import('./public.js').ActionFailure<T>}
  */
 /**
- * Create an `ActionFailure` object.
+ * Create an `ActionFailure` object. Call when form submission fails.
  * @param {number} status
  * @param {any} [data]
  * @returns {import('./public.js').ActionFailure<any>}

packages/kit/types/index.d.ts

@@ -2001,12 +2001,12 @@ declare module '@sveltejs/kit' {
 	 */
 	export function text(body: string, init?: ResponseInit | undefined): Response;
 	/**
-	 * Create an `ActionFailure` object.
+	 * Create an `ActionFailure` object. Call when form submission fails.
 	 * @param status The [HTTP status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#client_error_responses). Must be in the range 400-599.
 	 * */
 	export function fail(status: number): ActionFailure<undefined>;
 	/**
-	 * Create an `ActionFailure` object.
+	 * Create an `ActionFailure` object. Call when form submission fails.
 	 * @param status The [HTTP status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#client_error_responses). Must be in the range 400-599.
 	 * @param data Data associated with the failure (e.g. validation errors)
 	 * */