Add documentation

play-json-generic/src/main/scala-3/com/evolution/playjson/generic/FlatTypeReads.scala

@@ -10,6 +10,9 @@ import scala.annotation.nowarn
  * It will look for a `type` field in the JSON object and use its value to determine which subtype to use.
  * The `type` field will be removed from the JSON object before the subtype's `Reads` is called.
  * 
+ * The difference between this class and `NestedTypeReads` is that this class uses the simple name of the subtype
+ * instead of the full prefixed name. This means that you cannot use the same simple name for multiple subtypes.
+ * 
  * Example:
  * 
  * {{{

play-json-generic/src/main/scala-3/com/evolution/playjson/generic/NestedTypeReads.scala

@@ -4,6 +4,33 @@ import play.api.libs.json.*
 import scala.deriving.Mirror
 import scala.compiletime.*
 
+/**
+ * This is a helper class for creating a `Reads` instance for a sealed trait hierarchy.
+ * It will look for a `type` field in the JSON object and use its value to determine which subtype to use.
+ * The `type` field will be removed from the JSON object before the subtype's `Reads` is called.
+ * 
+ * The difference between this class and `FlatTypeReads` is that this class uses the full prefixed name of the subtype
+ * instead of just the simple name. This allows you to use the same simple name for multiple subtypes as long as they
+ * are located in different branches of the sealed trait hierarchy.
+ * 
+ * Example:
+ * {{{
+ * sealed trait Parent
+ * sealed trait Branch1 extends Parent
+ * sealed trait Branch2 extends Parent
+ * case class Child1(field1: String) extends Parent
+ * case class Child2(field2: Int) extends Parent
+ * 
+ * object Child1:
+ * given Reads[Child1] = Json.reads[Child1]
+ * object Child2:
+ * given Reads[Child2] = Json.reads[Child2]
+ * 
+ * val reads: NestedTypeReads[Parent] = summon[NestedTypeReads[Parent]]
+ * 
+ * }}} 
+ * 
+ */
 trait NestedTypeReads[T] extends Reads[T]:
  override def reads(jsValue: JsValue): JsResult[T]
 
@@ -13,6 +40,14 @@ object NestedTypeReads:
  def create[A](f: JsValue => JsResult[A]): NestedTypeReads[A] =
  (jsValue: JsValue) => f(jsValue)
 
+ /**
+ * This is the first method that will be called when the compiler is looking for an instance of `NestedTypeReads`.
+ * It will look for a `type` field in the JSON object and use its value to determine which subtype of `A` to use.
+ * Then, it will look for an instance of `Reads` for that subtype and use it to read the JSON object.
+ *
+ * @param m
+ * @return
+ */
  inline given derive[A](using m: Mirror.SumOf[A]): NestedTypeReads[A] =
  create[A] { jsValue =>
  for {
@@ -24,6 +59,16 @@ object NestedTypeReads:
  } yield result
  }
 
+ /**
+ * Traverse the tuple of types and look for a `Reads` instance for the type that matches the given `typ`.
+ * If no `Reads` instance is found, return `None`. Otherwise, return the `Reads` instance.
+ * This method is used to traverse the tuple of types that represent the subtypes of a sealed trait.
+ *
+ * @param typ the value of the `type` field in the JSON object.
+ * @param prefix the prefix to use when building the full prefixed name of the subtype. 
+ * For example, if the `prefix` is `com.example` and the `typ` is `Child1`, the full prefixed name of the subtype
+ * is `com.example.Child1`. If the `prefix` is empty, the full prefixed name of the subtype is just the `typ`.
+ */
  private inline def deriveNestedTypeReadsForSum[A, T <: Tuple](
  typ: String,
  prefix: String