Reified: more javadoc

Olivier Chafik · Olivier Chafik · commit 97266327b6d9 · 2013-07-13T11:18:53.000+01:00
diff --git a/Reified/Doc/src/main/rootdoc.txt b/Reified/Doc/src/main/rootdoc.txt
@@ -1 +1,31 @@
-Scalaxy/Reify provides a reify method that goes beyond the stock Universe.reify method, by taking care of captured values and allowing composition of reified functions for improved flexibility of dynamic usage of ASTs. The original expression is also available at runtime, without having to compile it with ToolBox.eval.
+Scalaxy/Reify provides a powerful reified values mechanism that deals well with composition and captures of runtime values, allowing for complex ASTs to be generated during runtime for re-compilation or transformation purposes. 
+
+It preserves the original value that was reified, allowing for flexible mixed usage of runtime value and compile-time AST.
+
+Please look at documentation of [[scalaxy.reified.reify]] and [[scalaxy.reified.ReifiedValue]] first.
+
+{{{
+import scalaxy.reified._
+
+def comp(capture1: Int): ReifiedFunction1[Int, Int] = {
+  val capture2 = Seq(10, 20, 30)
+  val f = reify((x: Int) => capture1 + capture2(x))
+  val g = reify((x: Int) => x * x)
+  
+  g.compose(f)
+}
+
+val f = comp(10)
+// Normal evaluation, using regular function:
+println(f(1))
+
+// Get the function's AST, inlining all captured values and captured reified values:
+val ast = f.expr().tree
+println(ast) 
+
+// Compile the AST at runtime (needs scala-compiler.jar in the classpath).
+// This is an optimized compilation by default, soon with extra optimizing AST transforms taken from Scalaxy.
+val compiledF = ast.compile()()
+// Evaluation, using the freshly-compiled function:
+println(compiledF(1))
+}}}
diff --git a/Reified/src/main/scala/scalaxy/reified/package.scala b/Reified/src/main/scala/scalaxy/reified/package.scala
@@ -87,6 +87,10 @@ package object reified {
     }
     */
 
+    /**
+     * Creates a tupled version of this reified function: instead of 2 arguments, it accepts a
+     * single `scala.Tuple2` argument.
+     */
     def tupled: ReifiedFunction1[(T1, T2), R] = {
       val f = this
       internal.reifyMacro((p: (T1, T2)) => {
