feat(88): Added Scaladoc

core/src/main/scala/in/rcard/raise4s/Raise.scala

@@ -1769,6 +1769,34 @@ object Raise {
   inline def withDefault[Error, A](default: A)(inline block: Raise[Error] ?=> A): A =
     Raise.recover(block)(error => default)
 
+  /** Add tracing to a block of code that can raise a logical error. In detail, the logical error is
+    * wrapped inside a [[Traced]] exception and processed by the [[TraceWith]] strategy instance.
+    * Please, be aware that adding tracing to an error can have a performance impact since a fat
+    * exception with a full stack trace is created.
+    *
+    * <h2>Example</h2>
+    * {{{
+    * given TraceWith[String] = trace => {
+    *   trace.printStackTrace()
+    * }
+    * val lambda: Int raises String = traced {
+    *   raise("Oops!")
+    * }
+    * val actual: String | Int = Raise.run(lambda)
+    * actual shouldBe "Oops!"
+    * }}}
+    *
+    * @param block
+    *   The block of code to execute that can raise an error
+    * @param tracing
+    *   The strategy to process the traced error
+    * @tparam Error
+    *   The type of the logical error that can be raised by the `block` lambda
+    * @tparam A
+    *   The type of the result of the execution of `block` lambda
+    * @return
+    *   The original block wrapped into a traced block
+    */
   inline def traced[Error, A](
       inline block: Raise[Error] ?=> A
   )(using inline tracing: TraceWith[Error]): Raise[Error] ?=> A = {

core/src/main/scala/in/rcard/raise4s/Strategies.scala

@@ -72,12 +72,41 @@ object Strategies {
   trait RecoverWith[Error, A] {
     def recover(error: Error): A
   }
-
+
+  /** Implement the `raise` method to throw a [[Traced]] exception with the error to trace instead
+    * of a [[Raised]] exception.
+    */
   private[raise4s] class TracedRaise extends Raise[Any]:
     def raise(e: Any): Nothing = throw Traced(e)
 
+  /** The exception that wraps the original error in case of tracing. The difference with the [[Raised]] exception is that
+   * the exception contains a full stack trace.
+    * @param original
+    *   The original error to trace
+    * @tparam Error
+    *   The type of the error to trace
+    */
   case class Traced[Error](original: Error) extends Exception
 
+  /** A strategy that allows to trace an error and return it. The [[trace]] method represent the
+    * behavior to trace the error. As a strategy, it should be used as a `given` instance. Use the
+    * type class instance with the [[Raise.traced]] DSL.
+    *
+    * <h2>Example</h2>
+    * {{{
+    * given TraceWith[String] = trace => {
+    *   trace.printStackTrace()
+    * }
+    * val lambda: Int raises String = traced {
+    *   raise("Oops!")
+    * }
+    * val actual: String | Int = Raise.run(lambda)
+    * actual shouldBe "Oops!"
+    * }}}
+    *
+    * @tparam Error
+    *   The type of the error to trace
+    */
   trait TraceWith[Error] {
     def trace(traced: Traced[Error]): Unit
   }