From 3012146c06d93c31a7e42376370b86d627577fca Mon Sep 17 00:00:00 2001
From: rcardin <riccardo.cardin@gmail.com>
Date: Mon, 30 Dec 2024 14:50:00 +0100
Subject: [PATCH] feat(88): Added Scaladoc

---
 .../main/scala/in/rcard/raise4s/Raise.scala   | 28 +++++++++++++++++
 .../scala/in/rcard/raise4s/Strategies.scala   | 31 ++++++++++++++++++-
 2 files changed, 58 insertions(+), 1 deletion(-)

diff --git a/core/src/main/scala/in/rcard/raise4s/Raise.scala b/core/src/main/scala/in/rcard/raise4s/Raise.scala
index 2d3311a..a898dd5 100644
--- a/core/src/main/scala/in/rcard/raise4s/Raise.scala
+++ b/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 = {
diff --git a/core/src/main/scala/in/rcard/raise4s/Strategies.scala b/core/src/main/scala/in/rcard/raise4s/Strategies.scala
index a628c28..2586ce5 100644
--- a/core/src/main/scala/in/rcard/raise4s/Strategies.scala
+++ b/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
   }