a bit more documentation

julienrf · julienrf · commit 48f0a47a1b5a · 2014-01-17T23:25:31.000+01:00
diff --git a/README.md b/README.md
@@ -1,11 +1,48 @@
 # js-scala: JavaScript as an embedded DSL in Scala #
 
-### Documentation
+js-scala is a Scala library providing composable JavaScript code generators as embedded DSLs. Generate (optimized) JavaScript code from Scala-like code:
+
+```scala
+import scala.js.language.JS
+trait JavaScriptGreet extends JS {
+
+  def greet(name: Rep[String]): Rep[Unit] = {
+    println("Hello, " + name + "!")
+  }
+
+}
+```
+
+`greet` is a JavaScript program generator that produces a program that prints a message in the console. The JavaScript code can be produced as follows:
+
+```scala
+import scala.js.exp.JSExp
+import scala.js.gen.js.GenJS
+object Generator extends App {
+  val javaScriptGreet = new JavaScriptGreet with JSExp
+  val codeGen = new GenJS { val IR: javaScriptGreet.type = javaScriptGreet }
+  codeGen.emitSource(javaScriptGreet.greet, "greet", new java.io.PrintWriter(System.out))
+}
+```
+
+Running the above Scala program will print the following on the standard output:
+
+```javascript
+function greet(x0) {
+  var x1 = "Hello, "+x0;
+  var x2 = x1+"!";
+  var x3 = console.log(x2);
+}
+```
+
+## Publications and talks
 
 * ECOOP 2012 paper ([PDF](http://infoscience.epfl.ch/record/179888/files/js-scala-ecoop.pdf)) and slides ([PDF](http://pldi12.cs.purdue.edu/sites/default/files/slides_ecoop_gkossakowski.pdf))
 * [Scala Days 2012 talk](http://skillsmatter.com/podcast/scala/javascript-embedded-dsl-scala)
+* mloc-js'13 talk ([slides](http://prezi.com/l23gghh7c27t/?utm_campaign=share&utm_medium=copy&rc=ex0share))
+* GPCE'13 paper ([PDF](https://github.com/js-scala/js-scala/raw/master/papers/gpce2013/gpce19c-foy.pdf)) and [slides](https://docs.google.com/presentation/d/1ErPjZMTheuKwp428QpxWibZlyjK3PKijwKtYEaXWoxQ/pub?start=false&loop=false&delayms=3000)
 
-### Setup
+## Setup
 
 1. Setup [virtualization-lms-core](http://github.com/TiarkRompf/virtualization-lms-core):
   - `$ git clone git@github.com:TiarkRompf/virtualization-lms-core.git`
@@ -20,11 +57,14 @@
   - `> test`
 4. Publish it (if you want to use it in your project):
   - `> publish-local`
-5. Run the examples:
+5. Generate the API documentation:
+  - `> doc`
+  - The documentation is generated in the `core/target/scala-2.10/api/` directory.
+6. Run the examples:
   - `> project examples`
   - `> run`
 
-### Use it in your project
+## Use it in your project
 
 1. Add a dependency on js-scala 0.4-SNAPSHOT
   - `libraryDependencies += "EPFL" %% "js-scala" % "0.4-SNAPSHOT"`
@@ -34,8 +74,14 @@
 3. Set the `-Yvirtualize` compiler option
   - `scalacOptions += "-Yvirtualize"`
 
-### Further projects
+## Further projects
 
 * [play-js-validation](http://github.com/js-scala/play-js-validation) uses this DSL to enable form validation code in Play 2.0 to be written once and checked on both client and server sides.
 
 * [forest](http://github.com/js-scala/forest) uses this DSL to enable HTML templates to be written once and shared between client and server sides, both for initial rendering and automatic updating.
+
+## Quick start
+
+First, be sure to be familiar with [LMS tutorials](http://scala-lms.github.io/tutorials).
+
+(More to come!)
diff --git a/core/src/main/scala/scala/js/language/JS.scala b/core/src/main/scala/scala/js/language/JS.scala
@@ -5,4 +5,7 @@ package scala.js.language
  */
 trait JSBase extends JsScalaBase with Dynamics with Arrays with RegExps with OptionOps
 
+/**
+ * Same as [[scala.js.language.JSBase]] but with implicit conversions automatically lifting values to `Rep` values when needed.
+ */
 trait JS extends JSBase with JsScala
diff --git a/core/src/main/scala/scala/js/language/JsScala.scala b/core/src/main/scala/scala/js/language/JsScala.scala
@@ -5,10 +5,15 @@ import scala.virtualization.lms.common._
 /**
  * Trait aggregating several DSLs providing a base language for Web programming with the ability to share code
  * between server and client sides.
+ *
+ * Integrates most of the language units defined by LMS.
  */
 trait JsScalaBase extends Base with NumericOps with OrderingOps with Equal with IfThenElse
   with While with BooleanOps with StringOps with Variables with ListOps with ObjectOps
   with TupledFunctions with Structs with PrimitiveOps with MiscOps with TupleOps with ListOps2
 
+/**
+ * Same as [[scala.js.language.JsScala]] but with implicit conversions automatically lifting values to `Rep` values when needed.
+ */
 trait JsScala extends JsScalaBase with LiftVariables with LiftEquals with LiftNumeric with LiftString with LiftBoolean
   with LiftPrimitives
diff --git a/core/src/main/scala/scala/js/language/ListOps2.scala b/core/src/main/scala/scala/js/language/ListOps2.scala
@@ -2,6 +2,9 @@ package scala.js.language
 
 import scala.virtualization.lms.common.Base
 
+/**
+ * Add more operations on lists than those provided by LMS.
+ */
 trait ListOps2 extends Base {
   implicit class ListOps2[A](l: Rep[List[A]]) {
     def mkString2(sep: Rep[String]) = list_mkString2(l, sep)
diff --git a/core/src/main/scala/scala/js/language/OptionOps.scala b/core/src/main/scala/scala/js/language/OptionOps.scala
@@ -2,6 +2,9 @@ package scala.js.language
 
 import scala.virtualization.lms.common.Base
 
+/**
+ * Language unit for optional values manipulation (similar to [[scala.Option]] type).
+ */
 trait OptionOps extends Base {
 
   val none: Rep[None.type]
diff --git a/core/src/main/scala/scala/js/language/dom/Browser.scala b/core/src/main/scala/scala/js/language/dom/Browser.scala
@@ -2,6 +2,9 @@ package scala.js.language.dom
 
 import scala.virtualization.lms.common.Base
 
+/**
+ * Web browser related API.
+ */
 trait Browser extends Base with SelectorOps with EventOps with ElementOps {
 
   trait Window extends EventTarget
diff --git a/core/src/main/scala/scala/js/language/dom/Dom.scala b/core/src/main/scala/scala/js/language/dom/Dom.scala
@@ -1,3 +1,6 @@
 package scala.js.language.dom
 
+/**
+ * Aggregates all the DOM API.
+ */
 trait Dom extends Core with ElementOps with EventOps with NodeListOps with Browser with SelectorOps
diff --git a/core/src/main/scala/scala/js/language/dom/ElementOps.scala b/core/src/main/scala/scala/js/language/dom/ElementOps.scala
@@ -2,6 +2,9 @@ package scala.js.language.dom
 
 import scala.virtualization.lms.common.Base
 
+/**
+ * [[org.w3c.dom.Element]] manipulation.
+ */
 trait ElementOps extends Base with EventOps with SelectorOps with Core {
 
   trait CSSStyleDeclaration
diff --git a/core/src/main/scala/scala/js/language/dom/EventOps.scala b/core/src/main/scala/scala/js/language/dom/EventOps.scala
@@ -1,7 +1,10 @@
 package scala.js.language.dom
 
 import scala.virtualization.lms.common.Base
- 
+
+/**
+ * [[org.w3c.dom.events.Event]] manipulation.
+ */
 trait EventOps extends Base {
 
   trait EventTarget
diff --git a/core/src/main/scala/scala/js/language/dom/NodeListOps.scala b/core/src/main/scala/scala/js/language/dom/NodeListOps.scala
@@ -2,6 +2,9 @@ package scala.js.language.dom
 
 import scala.virtualization.lms.common.Base
 
+/**
+ * [[org.w3c.dom.NodeList]] manipulation.
+ */
 trait NodeListOps extends Base {
 
   class NodeList[A]
diff --git a/core/src/main/scala/scala/js/language/dom/SelectorOps.scala b/core/src/main/scala/scala/js/language/dom/SelectorOps.scala
@@ -2,6 +2,9 @@ package scala.js.language.dom
 
 import scala.virtualization.lms.common.Base
 
+/**
+ * Selector API.
+ */
 trait SelectorOps extends Base with NodeListOps { this: ElementOps =>
 
   class Selectable[A]
@@ -15,8 +18,10 @@ trait SelectorOps extends Base with NodeListOps { this: ElementOps =>
     def find[A : Selectable : Manifest](selector: Rep[String]) = selector_find[A](s, selector)
     def findAll[A : Selectable : Manifest](selector: Rep[String]) = selector_findAll(s, selector)
   }
+  /** querySelector */
   // Note that selector_find[A](…)(implicit ev: A <:< Element) was simpler but sometimes didn’t make the type inferencer happy
   def selector_find[A : Selectable : Manifest](s: Rep[Selector], selector: Rep[String]): Rep[Option[A]]
+  /** querySelectorAll */
   def selector_findAll[A : Selectable : Manifest](s: Rep[Selector], selector: Rep[String]): Rep[NodeList[A]]
 
 }
