Detailed the difference between Failure and Exception

1 files changed, 9 insertions, 1 deletions

diff --git a/main/api/src/mill/api/Result.scala b/main/api/src/mill/api/Result.scala
index c1aa5c5c..f6579abd 100644
--- a/main/api/src/mill/api/Result.scala
+++ b/main/api/src/mill/api/Result.scala
@@ -39,18 +39,26 @@ object Result {
   sealed trait Failing[+T] extends Result[T] {
     def map[V](f: T => V): Failing[V]
   }
+
+  /**
+   * An intensional failure, which provides a proper error message as well as an optional result value.
+   * @param msg The error message.
+   * @param value The optional result value.
+   * @tparam T The result type of the computed task.
+   */
   case class Failure[T](msg: String, value: Option[T] = None) extends Failing[T] {
     def map[V](f: T => V) = Result.Failure(msg, value.map(f(_)))
   }
 
   /**
-   * A failed task which failed with a concrete exception.
+   * An (mostly) unintentionally failed task which the exception that caused the failure.
    * @param throwable The exception that describes or caused the failure.
    * @param outerStack The [[OuterStack]] of the failed task.
    */
   case class Exception(throwable: Throwable, outerStack: OuterStack) extends Failing[Nothing] {
     def map[V](f: Nothing => V) = this
   }
+
   class OuterStack(val value: Seq[StackTraceElement]) {
     override def hashCode() = value.hashCode()