Documentation updates

bryanjos · bryanjos · commit 279e404aa2d7 · 2017-08-08T09:36:20.000-05:00
diff --git a/GettingStarted.md b/GettingStarted.md
@@ -1,16 +1,20 @@
-# Getting Started with ElixirScript
+# Getting Started
 
 The intent of this guide is to get you started with ElixirScript. It will give you instructions on using ElixirScript.
 
-Adding Elixirscript to your mix project gives you the ability to add it to your list of mix compilers. This means when you `mix compile`, Elixirscript will compile your code as well.
+Adding ElixirScript to your mix project gives you the ability to add it to your list of mix compilers. This means when you `mix compile`, ElixirScript will compile your code as well.
 
 Add dependency to your deps in mix.exs:
 
 ``` elixir
 {:elixir_script, "~> 0.30"}
 ```
 
-Elixirscript uses default output and module formats if options are not given. If you wish to change any or all options, add an `elixir_script` key to your project configuration.
+Next make sure to add ElixirScript to your list of compilers in mix.exs.
+
+ElixirScript must be told which modules to use as the entry to your ElixirScript application. This is done by adding an `elixir_script` key to your project configuration. This must be a keyword list. Add an `input` key and make the value either the name of a module or a list of modules that are the entry modules you wish to compile to JavaScript. ElixirScript will use those modules to find what other modules and functions it needs to convert to JavaScript. ElixirScript by default places output in `priv/elixir_script/build`. If you wish to change this, add an `output` key to your ElixirScript configuration.
+
+An example configuration for a project is shown below
 
 ``` elixir
     def project do
@@ -19,18 +23,22 @@ Elixirscript uses default output and module formats if options are not given. If
      version: "0.1.0",
      elixir: "~> 1.0",
      deps: deps,
+     # Add elixir_script as a compilter
+     compilers: Mix.compilers ++ [:elixir_script],
+     # Our elixir_script configuration
      elixir_script: [
+        # Entry module. Can also be a list of modules
         input: MyEntryModule,
+        # Output path. Either a path to a js file or a directory
         output: "priv/elixir_script/build/Elixir.App.js"
-     ],
-     compilers: Mix.compilers ++ [:elixir_script]
+     ]
     ]
     end
 ```
 
 Available options are:
 
-* `input`: The entry module(s) for your application or library
+* `input` (required): The entry module(s) for your application or library
 
 * `output`: The path of the generated JavaScript file. (defaults to `priv/elixir_script/build`)
 
@@ -53,10 +61,10 @@ Now run `mix compile` and you should see a JavaScript file named `Elixir.App.js`
 
 If your browser does not yet support ES modules directly, use a tool such as [webpack](https://webpack.js.org/) or [brunch](http://brunch.io/) to convert it into something that can be used in the browser
 
-### Macros
-
-Elixirscript supports all macros
-
 ### JavaScript Interop
 
 Check out the [JavaScript Interoperability](JavascriptInterop.html) documentation
+
+### Limitations
+
+ElixirScript does not support `receive` or any of OTP at this time.
diff --git a/JavascriptInterop.md b/JavascriptInterop.md
@@ -5,7 +5,7 @@
 ### ElixirScript.JS module
 
 The `ElixirScript.JS` module has functions and macros that help with interacting with JavaScript.
-These mostly correspond to JavaScript keywords that may be useful.
+Most of them correspond to JavaScript keywords that may be useful.
 
 ```elixir
 # Calling the JavaScript Debugger
@@ -17,7 +17,7 @@ ElixirScript.JS.typeof(my_value)
 
 ### Foreign Function Interface
 
-ElixirScript calls JavaScript modules through a Foreign Function Interface (FFI). A foreign module is defined by creating a new module and adding `use ElixirScript.FFI` to it.
+ElixirScript calls JavaScript modules through a Foreign Function Interface (FFI). A foreign module is defined by creating a new Elixir module and adding `use ElixirScript.FFI` to it.
 
 Here is an example of a foreign module for a JSON module
 
diff --git a/lib/elixir_script/compiler.ex b/lib/elixir_script/compiler.ex
@@ -1,15 +1,28 @@
 defmodule ElixirScript.Compiler do
   @moduledoc """
-  Compiles the given modules to JavaScript.
+  The entry point for the ElixirScript compilation process.
+  Takes the given module(s) and compiles them and all modules
+  and functions they use into JavaScript
   """
 
   @doc """
   Takes either a module name or a list of module names as
   the entry point(s) of an application/library. From there
   it will determine which modules and functions are needed
   to be compiled.
+
+  Available options are:
+  * `output`: The path of the generated JavaScript file.
+
+    If output is `nil`, then generated code is sent to standard out
+
+    If output is a path, the generated code placed in that path.
+    If path ends in `.js` then that will be the name of the file.
+    If a directory is given, file will be named `Elixir.App.js`
+
+  * `root`: Optional root for imports of FFI JavaScript modules. Defaults to `.`.
   """
-  @spec compile([atom], []) :: nil
+  @spec compile(atom | [atom], []) :: nil
   def compile(entry_modules, opts \\ []) do
     opts = build_compiler_options(opts, entry_modules)
     {:ok, pid} = ElixirScript.State.start_link(opts)
diff --git a/lib/elixir_script/ffi.ex b/lib/elixir_script/ffi.ex
@@ -1,6 +1,6 @@
 defmodule ElixirScript.FFI do
   @moduledoc """
-  The foreign function interface for interacting with JavaScript
+  The Foreign Function Interface (FFI) for interacting with JavaScript
 
   To define a foreign module, make a new module and add `use ElixirScript.FFI`. to it
   To define external functions, use the `defexternal` macro.
diff --git a/lib/elixir_script/lib/js.ex b/lib/elixir_script/lib/js.ex
@@ -10,8 +10,9 @@ defmodule ElixirScript.JS do
   @doc """
   Creates new JavaScript objects.
 
-  ex:
-    ElixirScript.JS.new User, ["first_name", "last_name"]
+  ```elixir
+  ElixirScript.JS.new User, ["first_name", "last_name"]
+  ```
   """
   defexternal new(module, params)
 
@@ -42,8 +43,10 @@ defmodule ElixirScript.JS do
 
   @doc """
   Mutates an existing JavaScript object.
-  ex:
-    ElixirScript.JS.mutate elem, "width", 100
+
+  ```elixir
+  ElixirScript.JS.mutate elem, "width", 100
+  ```
   """
   defexternal mutate(object, key, value)
 
@@ -52,8 +55,11 @@ defmodule ElixirScript.JS do
   Takes the given map and returns an object
   Throws an error if any key is not a
   number, binary, or atom
-  ex:
-    ElixirScript.JS.map_to_object(%{my: "map"})
+
+
+  ```elixir
+  ElixirScript.JS.map_to_object(%{my: "map"})
+  ```
   """
   defexternal map_to_object(object)
 end
diff --git a/lib/elixir_script/watcher.ex b/lib/elixir_script/watcher.ex
@@ -3,7 +3,10 @@ defmodule ElixirScript.Watcher do
   require Logger
 
   @moduledoc """
-  Watches the input folder for changes and calls the ElixirScript compiler
+  Watches for code changes and calls the ElixirScript compiler.
+
+  This module watches for changes in BEAM files. When there is a change,
+  it calls the ElixirScript compiler to recompile.
   """
 
 
diff --git a/lib/mix/tasks/compile.elixir_script.ex b/lib/mix/tasks/compile.elixir_script.ex
@@ -26,6 +26,9 @@ defmodule Mix.Tasks.Compile.ElixirScript do
     If path ends in `.js` then that will be the name of the file. If a directory is given,
     file will be named `Elixir.App.js`
 
+  * `root`: Optional root for imports of FFI JavaScript modules.
+  Defaults to `.`. If using output directly in a browser, you may want to make it something like `/js` or some uri.
+
   The mix compiler will also compile any dependencies that have the elixirscript compiler in its mix compilers as well
   """
 
