Add documentation for the @js functions and friends

src/rpc/rpc.jl

@@ -19,6 +19,22 @@ Base.showerror(io::IO, e::JSError) =
 
 export js, js_, @js, @js_, @var, @new
 
+"""
+    js(win, expr::JSString; callback=false)
+
+Execute the javscript in `expr`, inside `win`.
+
+If `callback==true`, returns the result of evaluating `expr`.
+"""
+function js end
+
+"""
+    JSString(str)
+
+A wrapper around a string indicating the string contains javascript code.
+"""
+function JSString end
+
 msg(o, m) = error("$(typeof(o)) object doesn't support JS messages")
 
 function js(o, js::JSString; callback = true)
@@ -44,10 +60,47 @@ end
 
 js(o, j; callback=true) = js(o, JSString(string(jsstring(j)...)); callback=callback)
 
+"""
+    @js win expr
+
+Execute `expr`, converted to javascript, inside `win`, and return the result.
+
+`expr` will be parsed as julia code, and then converted directly to the
+equivalent javascript. Language keywords that don't exist in julia can be
+represented with their macro equivalents, `@var`, `@new`, etc.
+
+See also: `@js_`, the asynchronous version.
+
+# Examples
+```julia-repl
+julia> @js win x = 5
+5
+julia> @js_ win for i in 1:x console.log(i) end
+```
+"""
 macro js(o, ex)
     :(js($(esc(o)), $(Expr(:quote, ex))))
 end
 
+"""
+    @js_ win expr
+
+Execute `expr`, converted to javascript, asynchronously inside `win`, and return
+immediately.
+
+`expr` will be parsed as julia code, and then converted directly to the
+equivalent javascript. Language keywords that don't exist in julia can be
+represented with their macro equivalents, `@var`, `@new`, etc.
+
+See also: `@js`, the synchronous version that returns its result.
+
+# Examples
+```julia-repl
+julia> @js win x = 5
+5
+julia> @js_ win for i in 1:x console.log(i) end
+```
+"""
 macro js_(o, ex)
     :(js($(esc(o)), $(Expr(:quote, ex)), callback=false))
 end