From e87ff295d024a77a949aa7db5ff79e35c94e1e89 Mon Sep 17 00:00:00 2001
From: sinclair <haydn.developer@gmail.com>
Date: Thu, 19 Dec 2024 17:23:48 +0900
Subject: [PATCH] Ref Documentation

---
 src/type/ref/ref.ts   | 25 +++++++++++++++++++------
 src/type/type/json.ts | 25 +++++++++++++++++++------
 2 files changed, 38 insertions(+), 12 deletions(-)

diff --git a/src/type/ref/ref.ts b/src/type/ref/ref.ts
index f50f6a7e..85e0e125 100644
--- a/src/type/ref/ref.ts
+++ b/src/type/ref/ref.ts
@@ -47,18 +47,31 @@ export type TRefUnsafe<Type extends TSchema> = TUnsafe<Static<Type>>
 /** `[Json]` Creates a Ref type.*/
 export function Ref<Ref extends string>($ref: Ref, options?: SchemaOptions): TRef<Ref>
 /**
- * @deprecated `[Json]` Creates a Ref type. The referenced type MUST contain a $id. The Ref(TSchema) signature was
- * deprecated on 0.34.0 in support of a new type referencing model (Module). Existing implementations using Ref(TSchema)
- * can migrate using the following. The Ref(TSchema) validation behavior of Ref will be preserved how the construction
- * of legacy Ref(TSchema) will require wrapping in TUnsafe (where TUnsafe is used for inference only)
+ * @deprecated `[Json]` Creates a Ref type. This signature was deprecated in 0.34.0 where Ref requires callers to pass
+ * a `string` value for the reference (and not a schema).
+ *
+ * To adhere to the 0.34.0 signature, Ref implementations should be updated to the following.
  *
  * ```typescript
+ * // pre-0.34.0
+ *
+ * const T = Type.String({ $id: 'T' })
+ *
  * const R = Type.Ref(T)
  * ```
- * to
+ * should be changed to the following
+ *
+ * ```typescript
+ * // post-0.34.0
+ *
+ * const T = Type.String({ $id: 'T' })
+ *
+ * const R = Type.Unsafe<Static<typeof T>>(Type.Ref('T'))
+ * ```
+ * You can also create a generic function to replicate the pre-0.34.0 signature if required
  *
  * ```typescript
- * const R = Type.Unsafe<Static<T>>(T.$id)
+ * const LegacyRef = <T extends TSchema>(schema: T) => Type.Unsafe<Static<T>>(Type.Ref(schema.$id!))
  * ```
  */
 export function Ref<Type extends TSchema>(type: Type, options?: SchemaOptions): TRefUnsafe<Type>
diff --git a/src/type/type/json.ts b/src/type/type/json.ts
index 8cbb88ef..afc3650d 100644
--- a/src/type/type/json.ts
+++ b/src/type/type/json.ts
@@ -269,18 +269,31 @@ export class JsonTypeBuilder {
   /** `[Json]` Creates a Ref type.*/
   public Ref<Ref extends string>($ref: Ref, options?: SchemaOptions): TRef<Ref>
   /**
-   * @deprecated `[Json]` Creates a Ref type. The referenced type MUST contain a $id. The Ref(TSchema) signature was
-   * deprecated on 0.34.0 in support of a new type referencing model (Module). Existing implementations using Ref(TSchema)
-   * can migrate using the following. The Ref(TSchema) validation behavior of Ref will be preserved how the construction
-   * of legacy Ref(TSchema) will require wrapping in TUnsafe (where TUnsafe is used for inference only)
+   * @deprecated `[Json]` Creates a Ref type. This signature was deprecated in 0.34.0 where Ref requires callers to pass
+   * a `string` value for the reference (and not a schema).
+   *
+   * To adhere to the 0.34.0 signature, Ref implementations should be updated to the following.
    *
    * ```typescript
+   * // pre-0.34.0
+   *
+   * const T = Type.String({ $id: 'T' })
+   *
    * const R = Type.Ref(T)
    * ```
-   * to
+   * should be changed to the following
+   *
+   * ```typescript
+   * // post-0.34.0
+   *
+   * const T = Type.String({ $id: 'T' })
+   *
+   * const R = Type.Unsafe<Static<typeof T>>(Type.Ref('T'))
+   * ```
+   * You can also create a generic function to replicate the pre-0.34.0 signature if required
    *
    * ```typescript
-   * const R = Type.Unsafe<Static<T>>(T.$id)
+   * const LegacyRef = <T extends TSchema>(schema: T) => Type.Unsafe<Static<T>>(Type.Ref(schema.$id!))
    * ```
    */
   public Ref<Type extends TSchema>(type: Type, options?: SchemaOptions): TRefUnsafe<Type>