Updated Code docs

Author: jwarwick

lib/elixir/lib/code.ex

@@ -6,24 +6,24 @@ defmodule Code do
   end
 
   @moduledoc """
-  The Code module is responsible for managing code compilation,
-  code evaluation and code loading.
+  Utilities for managing code compilation, code evaluation and code loading.
 
-  It complements [Erlang's code module](http://www.erlang.org/doc/man/code.html)
+  This module complements [Erlang's code module](http://www.erlang.org/doc/man/code.html)
   to add behavior which is specific to Elixir.
 
   """
 
   @doc """
-  Returns all loaded files.
+  List all loaded files.
   """
   def loaded_files do
     :elixir_code_server.call :loaded
   end
 
   @doc """
-  Removes the given files from the loaded files list.
-  The modules defined in the file are not removed,
+  Remove files from the loaded files list.
+
+  The modules defined in the file are not removed;
   calling this function only removes them from the list,
   allowing them to be required again.
   """
@@ -32,33 +32,39 @@ defmodule Code do
   end
 
   @doc """
-  Appends a path to the Erlang VM code path.
+  Append a path to the Erlang VM code path.
+
   The path is expanded with `Path.expand/1` before being appended.
   """
   def append_path(path) do
     :code.add_pathz(Path.expand to_char_list(path))
   end
 
   @doc """
-  Prepends a path to the Erlang VM code path.
+  Prepend a path to the Erlang VM code path.
+
   The path is expanded with `Path.expand/1` before being prepended.
   """
   def prepend_path(path) do
     :code.add_patha(Path.expand to_char_list(path))
   end
 
   @doc """
-  Deletes a path from the Erlang VM code path.
+  Delete a path from the Erlang VM code path.
+
   The path is expanded with `Path.expand/1` before being deleted.
   """
   def delete_path(path) do
     :code.del_path(Path.expand to_char_list(path))
   end
 
   @doc """
-  Evaluates the contents given by `string`. The second argument is
-  a keyword list of variable bindings, followed by a keyword list of
-  environment options. Those options can be:
+  Evaluate the contents given by `string`. 
+
+  The `binding` argument is a keyword list of variable bindings. 
+  The `opts` argument is a keyword list of environment options. 
+  
+  Those options can be:
 
   * `:file` - the file to be considered in the evaluation
   * `:line` - the line on which the script starts
@@ -88,8 +94,7 @@ defmodule Code do
 
   `binding` is a keyword list with the value of all variable bindings
   after evaluating `string`. The binding key is usually an atom, but it
-  may be a tuple for variables defined in another contexts that are not
-  the main one.
+  may be a tuple for variables defined in a different context.
 
   ## Examples
 
@@ -127,7 +132,7 @@ defmodule Code do
   end
 
   @doc """
-  Evaluates the quoted contents.
+  Evaluate the quoted contents.
 
   See `eval_string/3` for a description of arguments and return values.
 
@@ -200,7 +205,9 @@ defmodule Code do
   end
 
   @doc """
-  Converts the given string to its quoted form. Returns `{ :ok, quoted_form }`
+  Convert the given string to its quoted form. 
+  
+  Returns `{ :ok, quoted_form }`
   if it succeeds, `{ :error, { line, error, token } }` otherwise.
 
   ## Options
@@ -213,10 +220,10 @@ defmodule Code do
   * `:existing_atoms_only` - When `true`, raises an error
     when non-existing atoms are found by the tokenizer.
 
-  ## Macro.to_string/1
+  ## Macro.to_string/2
 
   The opposite of converting a string to its quoted form is
-  `Macro.to_string/1`, which converts a quoted form to a string/binary
+  `Macro.to_string/2`, which converts a quoted form to a string/binary
   representation.
   """
   def string_to_quoted(string, opts // []) when is_list(opts) do
@@ -231,7 +238,9 @@ defmodule Code do
   end
 
   @doc """
-  Converts the given string to its quoted form. It returns the ast if it succeeds,
+  Convert the given string to its quoted form. 
+  
+  It returns the ast if it succeeds,
   raises an exception otherwise. The exception is a `TokenMissingError`
   in case a token is missing (usually because the expression is incomplete),
   `SyntaxError` otherwise.
@@ -250,7 +259,9 @@ defmodule Code do
   defp unpack_quote(line, forms),                            do: { :__block__, [line: line], forms }
 
   @doc """
-  Loads the given `file`. Accepts `relative_to` as an argument to tell where
+  Load the given file. 
+  
+  Accepts `relative_to` as an argument to tell where
   the file is located. If the file was already required/loaded, loads it again.
   It returns a list of tuples `{ ModuleName, <<byte_code>> }`, one tuple for each
   module defined in the file.
@@ -270,9 +281,11 @@ defmodule Code do
   end
 
   @doc """
-  Requires the given `file`. Accepts `relative_to` as an argument to tell where
+  Require the given `file`. 
+  
+  Accepts `relative_to` as an argument to tell where
   the file is located. The return value is the same as that of `load_file/2`. If
-  the file was already required/loaded, doesn't do anything and returns nil.
+  the file was already required/loaded, doesn't do anything and returns `nil`.
 
   Notice that if `require_file` is invoked by different processes concurrently,
   the first process to invoke `require_file` acquires a lock and the remaining
@@ -298,16 +311,18 @@ defmodule Code do
   end
 
   @doc """
-  Loads the compilation options from the code server.
+  Load the compilation options from the code server.
+
   Check `compiler_options/1` for more information.
   """
   def compiler_options do
     :elixir_code_server.call :compiler_options
   end
 
   @doc """
-  Sets compilation options. These options are global
-  since they are stored by Elixir's Code Server.
+  Set compilation options. 
+
+  These options are global since they are stored by Elixir's Code Server.
 
   Available options are:
 
@@ -316,7 +331,7 @@ defmodule Code do
 
   * `:debug_info` - when `true`, retain debug information in the compiled module.
     This allows a developer to reconstruct the original source
-    code, for such reasons, `false` by default;
+    code, `false` by default;
 
   * `:ignore_module_conflict` - when `true`, override modules that were already defined
     without raising errors, `false` by default;
@@ -329,7 +344,9 @@ defmodule Code do
   end
 
   @doc """
-  Compiles the given string and returns a list of tuples where
+  Compile the given string. 
+
+  Returns a list of tuples where
   the first element is the module name and the second one is its
   binary.
 
@@ -340,7 +357,9 @@ defmodule Code do
   end
 
   @doc """
-  Compiles the quoted expression and returns a list of tuples where
+  Compile the quoted expression. 
+  
+  Returns a list of tuples where
   the first element is the module name and the second one is its
   binary.
   """
@@ -349,8 +368,10 @@ defmodule Code do
   end
 
   @doc """
-  Ensures the given module is loaded. If the module is already
-  loaded, it works as no-op. If the module was not yet loaded,
+  Ensure the given module is loaded. 
+  
+  If the module is already
+  loaded, this works as no-op. If the module was not yet loaded,
   it tries to load it.
 
   If it succeeds loading the module, it returns
@@ -391,15 +412,19 @@ defmodule Code do
   end
 
   @doc """
-  Similar to `ensure_loaded/1`, but returns a boolean in case
-  it could be ensured or not.
+  Ensure the given module is loaded.
+
+  Similar to `ensure_loaded/1`, but returns `true` if the module
+  is already loaded or was successfully loaded. Returns `false` otherwise.
   """
   def ensure_loaded?(module) do
     match?({ :module, ^module }, ensure_loaded(module))
   end
 
   @doc """
-  Ensures the given module is compiled and loaded. If the module
+  Ensure the given module is compiled and loaded. 
+  
+  If the module
   is already loaded, it works as no-op. If the module was not
   loaded yet, it checks if it needs to be compiled first and
   then tries to load it.
@@ -429,8 +454,11 @@ defmodule Code do
   end
 
   @doc """
-  Similar to `ensure_compiled/1`, but returns a boolean in case
-  it could be ensured or not.
+  Ensure the given module is compiled and loaded. 
+
+  Similar to `ensure_compiled/1`, but returns `true` if the module
+  is already loaded or was successfully loaded and compiled. 
+  Returns `false` otherwise.
   """
   def ensure_compiled?(module) do
     match?({ :module, ^module }, ensure_compiled(module))