Merge pull request #565 from Atry/shift-scaladoc

Add Scaladoc for Shift

Dsl/src/main/scala/com/thoughtworks/dsl/Dsl.scala

@@ -773,10 +773,10 @@ object Dsl extends LowPriorityDsl0 {
         run(keyword)
       }
 
-  extension [Keyword, Domain, Value](keyword: Keyword)
-    @inline def cpsApply(using
+  extension [Keyword, Value](keyword: Keyword)
+    @inline def cpsApply[Domain](using
         dsl: Dsl.Searching[Keyword, Domain, Value]
-    )(handler: Value => Domain)(using DummyImplicit): Domain = {
+    )(handler: Value => Domain): Domain = {
       dsl(keyword, handler)
     }
 

keywords-Shift/build.sbt

@@ -1,6 +1,3 @@
-scalacOptions in Compile ++= {
-  scalaBinaryVersion.value match {
-    case "2.11" => Some("–Xexperimental")
-    case _      => None
-  }
-}
+libraryDependencies += "org.scalatest" %%% "scalatest" % "3.2.10" % Test
+
+enablePlugins(Example)

keywords-Shift/src/main/scala/com/thoughtworks/dsl/keywords/Shift.scala

@@ -14,7 +14,47 @@ import scala.language.implicitConversions
 import scala.util.control.{NonFatal, TailCalls}
 import scala.util.control.TailCalls.TailRec
 
-/** @author
+/** A keyword that extracts the value from a [[domains.Continuation]].
+  * @note
+  *   This [[Shift]] keyword includes special treatment for exception handling
+  *   and stack safety. Always use `Shift(cont).cpsApply { x => ... }` instead
+  *   of `cont { x => ... }` to register a handler for the continuation,
+  *   otherwise exception might be uncaught or stack might overflow.
+  * @example
+  *   Given a continuation whose type is `Unit !! Throwable !! Int`, it is
+  *   considered as having an exception handler. When an exception is thrown,
+  * {{{
+  *   import scala.util.control.TailCalls.TailRec
+  *   type !![R, +A] = (A => R) => R
+  *   val cont: Unit !! Throwable !! Int = _ {
+  *     if (System.nanoTime() > 0) {
+  *       throw new Exception("my-exception")
+  *     } else {
+  *       42
+  *     }
+  *   }
+  * }}}
+  *
+  * Then `cpsApply` should catch the exception:
+  * {{{
+  *   Shift(cont).cpsApply[Unit !! Throwable] { i: Int => (failureHandler: Throwable => Unit) =>
+  *     fail("unreachable code")
+  *   } { e: Throwable =>
+  *     e.getMessage should be("my-exception")
+  *   }
+  * }}}
+  *
+  * However, `cont.apply` does not catch the exception:
+  * {{{
+  *   an[Exception] should be thrownBy {
+  *     cont.apply { i => failureHandler =>
+  *       fail("unreachable code")
+  *     } { e =>
+  *       e.getMessage should be("my-exception")
+  *     }
+  *   }
+  * }}}
+  * @author
   *   杨博 (Yang Bo)
   */
 opaque type Shift[R, A] <: Dsl.Keyword.Opaque = Dsl.Keyword.Opaque.Of[R !! A]